Java Agent Troubleshooting Framework Install

For the New Relic Java agent for APM, installation is a matter of adding the -javaagent:/path/to/newrelic.jar to the JVM options. This is often the same way as specifying the minimum and maximum heap memory values (-Xms and -Xmx).

Once you’ve “installed” the Java agent and started or restarted the JVM, you should see data reporting within a few minutes. If you’re having trouble, these are the steps that our support teams take to troubleshoot, and we hope they will help you find and resolve the issue quickly. If you have followed the troubleshooting steps in our No Data Appears (Java) Doc some of the below steps may be similar.

  1. Confirm the app is receiving traffic, has been for at least 5 min, and continues to receive traffic during troubleshooting

  2. Confirm your application meets the Agent’s Compatibility and Requirements. Some commercial software packages embed common frameworks in their product that create additional layers of complication.

  3. Run the Diagnostics CLI to collect data then validate the following…

    1. Validate the newrelic.yml configuration file. See
    2. Confirm Java process options, if a Java process is detected. Some versions of Java are not compatible with certain releases of our agent.
    3. Confirm there’s an agent log file
    4. Confirm OS, JDK/JRE version
    5. Confirm you are using the correct license key
    6. Verify the name of the application that should be reporting
    7. Check for High Security Mode configuration mismatches.
  4. Check application log for 2 lines branded with New Relic that tell which newrelic.yml file the configuration is being read from and to which file the logging information is being written

  5. Confirm the Java process includes the -javaagent parameter. We have some examples at Include the Java agent with a JVM argument but this is not an exhaustive list.

    • The command-line ps -ef JavaProcess should work for UNIX/LINUX.
    • For Windows there’s a myriad of tools: Task Manager, wmic, Powershell, Process Explorer
    • The process could have a name given by the vendor such as Tomcat
    • On Windows, the Java process could also be running as a service
  6. Check for the agent log. If there is no log, there’s a possibility that step 5 failed. Default location is in /logs under the location where the newrelic.jar file resides and the default file name is newrelic_agent.log

  7. If there is no file for step 3 above, check the newrelic.yml file for a configured file path log_file_path and log_file_name.

    • Alternately, there could be -Dnewrelic.config.log_file_path= and -Dnewrelic.config.log_file_name= parameters in the JVM options
    • Another option for setting config options is through Environment Variables, be aware of configuration settings order of precedence
  8. Confirm you restarted the application to pick up the -javaagent command?

    • If you are running on Windows, did you stop and restart the application?
    • If you are running on Windows and the application is running as a Windows Service, did you update the Windows Service
    • You may need to work with your internal teams for the above steps

There is a possibility with the various frameworks and embedded frameworks that are in COTS (Commercial Off The Shelf) software that the adding the -javaagent parameter could be hidden in a startup script, administrative console or even that the application comes up and spawns a new JVM instance that the parameters do not persist to so the agent just won’t get picked up that way.

Corner cases to keep in mind when troubleshooting:

  1. Some versions of Java use endorsed directories (-Djava.endorsed.dirs) but this was deprecated in more recent versions. If that option is set in the Java options, it means only the folders listed will be read by the JRE. If the agent is outside of the endorsed directories, it will be ignored even if it appears to be configured properly.

  2. If using Tableau Software, ensure you are not using a version that does not allow any updates to the JVM options hard-coded into their product. If this is the case you will need to work with Tableau or your internal teams to find a resolution.

  3. If another -javaagent is running in the JVM, it should still be okay in most circumstances but can cause issues. Sometimes swapping the order of the options so the New Relic agent loads first resolves these issues. If this does not resolve the issue it may be that the New Relic Agent and the other agent have a conflict of some type.

  4. If you are still unable to resolve the issue please reach out to New Relic Global Technical Support by going to Please be sure to mention, in as much detail as possible, the steps you have tried already and details of what you expect to see and what you are seeing.

1 Like

Thanks, @gsample for putting this together.
Can you compile certain checks and requirements around the SSL handshake that is required while interacting with the New Relic collectors? That is one area I’ve seen a lot of issues for that usually show up as PKIX exceptions in the logs.

@pillaivinil Even with the threads here on Explorer’s Hub giving the impression that it’s problematic the truth is that in a majority of scenarios things work without issue. Why the Java agent sees more reports of SSL exceptions is due to the JVM itself having a separate configuration for security apart from the Web Server. If the JVM has a custom trust store separate from the one that comes with the JDK, additional configuration is necessary so the agent is able to transmit the collected data to New Relic.
Fortunately, the Java agent repository is now available to our customers at providing better transparency on issues such as:

New Relic has to be quite careful in not telling customers how to configure their trust store as we want to not provide instruction that violates our customers’ internal organizational policies.

New Relic Documentation relevant to the Java agent and SSL

Java Docs relating to troubleshooting SSL Issues

I’ve also found this blog article helpful in providing direction on how to use the debug above to isolate the culprit,-ssl,-and-https

Let us know if this helps. It might be the basis of a future Level-Up Post or Troubleshooting Framework post.


Thanks @Jeanie_Swan for your inputs will go through the links shared.