Documentation forAppOptics

Troubleshooting (legacy agent)

The following content pertains to troubleshooting for the legacy AppOptics Java Agent.

AppOptics agents are no long receiving updates. The new SolarWinds Observability libraries can send APM data in AppOptics and are regularly updated with new features and improvements. If you are still relying on the AppOptics agents and your components are supported by the new libraries, consider transitioning to the SolarWinds Observability libraries for your APM needs. For more information about the benefits of migrating to the SolarWinds Observability libraries. Alternatively, you can use SolarWinds Observability as your primary APM solution.

If you have already transitioned to the new SolarWinds Observability Java Library, see the SolarWinds Java Library documentation for troubleshooting information.

SolarWinds Observability libraries are not compatible with AppOptics agents. Do not use a mix of SolarWinds Observability libraries and AppOptics agents to instrument applications that are part of a distributed trace.

If you are not receiving traces and metrics in your AppOptics dashboard these are some options to troubleshoot.

Is the APM agent connected to the AppOptics server?

  • If firewall is enabled for your host, you might want to whitelist our AppOptics server endpoints.

  • Connectivity diagnostic tool can be run using the same APM agent jar installed.

    For Java 6:

    java -Xbootclasspath/a:"C:\Program Files\AppOptics\APM\java\appoptics-agent.jar" com.appoptics.diagnostic.DiagnosticTools

    For Java 7+:

    java -cp "C:\Program Files\AppOptics\APM\java\appoptics-agent.jar" com.appoptics.diagnostic.DiagnosticTools
  • More details on the diagnostic can be found here.

Is the APM agent jar path accessible to the application user?

  • If an error message similar to below is found during application startup, then the agent jar path is either incorrect or the application user does not have permission to access the agent jar file.

    Error opening zip file or JAR manifest missing : /home/ec2-user/appoptics/appoptics-agent.jar
Error occurred during initialization of VM
agent library failed to init: instrument
  • Verify the javaagent file path and ensure the application user has read access to BOTH the agent jar file and its parent directory(ies).

Are requests being sent to the application?

  • Restart the application server and ensure that your application is receiving requests. In order for traces and metric data to be sent to your AppOptics dashboard your application must be receiving requests.

Do you have another profiler installed?

  • It is not recommended to run other APM agent alongside with our Java Agent. Disable other APM agents from your application process before starting your application with our Java Agent.

Has the agent been initialized?

  • Check if the agent has been enabled by inspecting the application server log files. The message Java agent version x.x.x started successfully should be printed upon successful agent startup, followed by 2 other messages with agent jar and config location information. If a message [AppOptics] Agent is disabled as agent.enabled is configured to false. is found, it means the agent is explicitly disabled by agent.enabled in javaagent.json or the corresponding environment variable APPOPTICS_AGENT_ENABLED.
  • One way to check if the agent has been initialized, is to look at the response headers returned. The agent will add the header X-Trace to the response. If the response doesn’t contain the header X-Trace, then the agent probably wasn’t loaded correctly.
  • Review the other troubleshooting options to try to resolve the issue.

Are requests being sampled for tracing?

  • Requests may not be sampled due to a low sample rate or connection issues. The X-Trace response header ends in 00 if a request isn’t traced and ends in 01 if the request is being traced.
  • Some requests should have a X-Trace header returned that ends in 01. If all X-Trace headers being returned end in 00 the server may not be able to connect to the AppOptics collector.
  • Review the application server logs for any connection issues logged by the agent.

Is the service key configured correctly?

  • The service key is added to the javaagent.json file (usually under the same directory as the agent jar appoptics-agent.jar). The first part of the service key (before the colon :) should match one of the AppOptic API tokens listed in the AppOptics dashboard under Organization Settings > API Tokens.

Where can agent logs be found?

How to increase log verbosity?

  • Increase the logging level verbosity to debug (default is info) to get more detailed information added to the agent logs. Use the agent configuration property LogLevel to change the logging level.
  • Restart the application server to have the new level take effect.
  • An application correctly configured with our Java Agent should log debug messages to System.out tagged with [AppOptics].

Are there warnings reported by the agent?

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

Is your application supported?

  • Out of the box, the agent instruments a wide range of servlet based containers, please refer to the Support Matrix for details.
  • If your application framework is not on the list, let us know! And consider using our SDK for custom instrumentation.