Documentation forSolarWinds Observability SaaS

Add a Java service

The Java Library provides automatic tracing and metrics for JVM-based languages. For new features, fixed issues, and updated components, see the Java Library release notes.

The Java Library is a custom distro based on the OpenTelemetry Java agent. In addition to the offering full compatibility with OpenTelemetry, the Java Library adds extra features.

Get started

Before you start

Verify the following to ensure the library can collect and transmit data:

  • The platform where your APM library will be installed is supported.

  • Your application components are supported by the library.

  • Your firewall configuration permits TCP/HTTPS/TLS outbound connections to apm.collector.xx-yy.cloud.solarwinds.com (where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs) using port 443. See Firewall or access control requirements.

    If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Remove other APM libraries from your Java application before using the SolarWinds Observability Java Library.

To enable instrumentation for a Java application and send the data to SolarWinds Observability SaaS:

  1. In SolarWinds Observability SaaS, click Add Data at the top.

  2. In the Add Data dialog Intro, click Monitor my application performance.

  3. Click Java.

  4. Type a name for your service and select the environment (self-managed Linux or self-managed Windows). Click Next.

  5. Create or select an API ingestion token to use when sending your collected service data by doing either of the following:

    • Select Generate New Token and enter an Ingestion Token Name, and then click Next.
    • Select Use Existing Token and select an ingestion token from the list, and then click Next.

  6. Download and install the library JAR on the host system.

  7. Set the service key and endpoint. These properties can be defined in the configuration file, set with environment variables, or defined in the Java system properties when loading the library.

    • See Service key for instructions to set the service key via environment variable or configuration file. The endpoint is apm.collector.xx-yy.cloud.solarwinds.com (where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs), and the Service key follows the format YourApiToken:YourServiceName. To find your Service key, look for the sw.apm.service.key property value in the code sample provided under Load the library into your application.

    • To define it in the Java system properties, see the next step.

  8. Load the library for monitoring. Use the code sample provided under Load the library into your application, but replace </path/to/solarwinds-apm-agent.jar> with the path to the .jar file downloaded earlier. For instructions for your specific web server, see Load the library.

    Restart the JVM to load the library.

  9. Wait for the Java Library to successfully connect to the SolarWinds APM collector and for the Waiting for Connection button in SolarWinds Observability SaaS to change to OK.

  10. Click OK to finish setting up the service.

    To view data collected for the newly configured entity in the Entity Explorer, click the name of the entity type in the confirmation dialog in the lower-left corner. It may take a few seconds for data to appear for the newly created entity. See Entity Explorer for details.

    For transaction and trace data to appear in the Entity Explorer and Traces Explorer, your service must be running and in use.

To tailor the installed library to your monitoring needs, see Configure the Java Library.

Custom instrumentation

Custom instrumentation can be used to get extra application-specific visibility in SolarWinds Observability SaaS, both adding custom spans for distributed tracing and adding custom timers or counters for alerting. See Java Library instrumentation SDK.

Code profiling

Code profiling provides extra insight into code level execution time that is otherwise not captured by auto-instrumentation. See code profiling and the Java-specific details for more on this feature.