Troubleshoot the Java Library

If you are not receiving traces and metrics in the Traces Explorer and Metrics Explorer, these are some options to troubleshoot.

Is the Java Library connected to the SolarWinds APM collector?

If your server is behind a firewall, you may not be able to connect to the SolarWinds APM collector. See Firewall or access control requirements for the URIs to add to firewall exclusions.

The connectivity diagnostic tool is part of the installed APM library JAR. See Diagnostics for usage information.

Is the Java Library JAR path accessible to the application user?

If an error message similar to below is found when the application starts up, either the library JAR path is incorrect or the application user does not have permission to access the library JAR file.

Error opening zip file or JAR manifest missing : /home/ec2-user/SolarWinds/solarwinds-apm-agent.jar
Error occurred during initialization of VM
agent library failed to init: instrument

Verify the Java Library file path and make sure the application user has read access to both the library JAR file and its parent directories.

Are requests sent to the application?

Restart the application server and make sure your application is receiving requests. Your application must receive requests in order for traces and metrics data to be sent to the Traces Explorer and Metrics Explorer.

Do you have another profiler installed?

It is not recommended to run another APM library alongside the SolarWinds Observability Java Library. Disable other APM libraries from your application before starting your application with the SolarWinds Observability Java Library.

Has the library been initialized?

Check if the library has been initialized by inspecting the application server log files. The message Successfully initialized SolarWindsAPM OpenTelemetry extensions with service key should be printed upon successful library startup.

Look at the response headers returned to see if the library has been initialized. The Java Library will add the header X-Trace to the response. If the response does not contain the header X-Trace, the library probably was not loaded correctly.

Review the other troubleshooting options to try to resolve the issue.

Are requests sampled for tracing?

If there is a low sample rate or connection issues, requests may not be sampled. The X-Trace response header ends in 00 if a request isn’t traced and ends in 01 if the request is being traced.

There should be some requests that return an X-Trace header ending in 01. If all X-Trace headers end in 00, this may indicate the server cannot connect to the SolarWinds APM collector.

Review the application server logs for any connection issues logged by the library.

Is the service key configured correctly?

The service key is defined as an environment variable or added to the solarwinds-apm-config.json file (usually located in the same directory as the solarwinds-apm-agent.jar library JAR).

The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

It is a required configuration and should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

Where can library logs be found?

Log messages from the library can be found in the application server log files.

How to increase log verbosity?

Increase the logging level verbosity to debug (default is info) to get more detailed information added to the library logs. Use the library configuration property LogLevel to change the logging level.

Restart the application server so the new level can take effect.

An application correctly configured with our Java Library should log debug messages to System.out tagged with [SolarWinds APM].

Are there warnings reported by the library?

Search the application server log files for WARNING [SolarWinds APM]. Sometimes configuration errors such as invalid formatting in the config file can lead to instrumentation problems.

Is your application supported?

The Java Library instruments a wide range of servlet based containers, see Support Matrix.

If your application framework is not on the list, use the SDK for custom instrumentation.