SolarWinds Observability: Introducing the New Java Agent

melanie.achard 9 months ago 8 minute read time

SolarWinds® Observability is a comprehensive monitoring solution that provides visibility into the health and performance of applications, infrastructure, networking, and user experience. SolarWinds Observability allows you to focus on key metrics without being overwhelmed by vast amounts of telemetry data. 

APM agents collect and sync performance metrics to your observability solution. SolarWinds has recently released a new Java agent, which is based on the OpenTelemetry Agent standards and supports its configuration options.

By bringing together all your services, infrastructure, and applications into one monitoring system, SolarWinds Observability reduces IT silos and enables better collaboration between various departments.

In this article, we will cover the key features of the Java agent, exploring how it integrates with SolarWinds Observability. We’ll also guide you on how to begin using the agent.

Key Features of the SolarWinds Observability Java Agent

The Java agent automatically traces and collects metrics for your JVM-based language projects. The agent requires minimal configuration and supports several configuration options for advanced use cases. 

Configuration options

The agent includes several configuration options for various endpoints and metrics:

Configuration	Description
Collector endpoint	The endpoint is where the library connects to and exports data. This endpoint needs to be defined using the format host:port. There are two ways to set the endpoint: 1. Set the agent.collector property in the APM config file. 2. Set the SW_APM_COLLECTOR environment variable.
Trusted certificate path	The library relies on the CA certificates configured for the JVM to authenticate the TLS connection to the collector. If you want to override the default settings, you can change the trusted certificate path configuration option to the absolute path of a specific trusted certificate file in PEM format. To use a custom trusted certificate path value, you can set the SW_APM_TRUSTEDPATH environment variable.
Logging level	This property allows you to change the logging level for your Java application. Its default value is info, but you could change it by setting the SW_APM_DEBUG_LEVEL environment variable. Changing the log level affects which application logs are synced with the observability platform. You could further customize your application’s logging configuration using the APM's detailed logging configuration guide.

Java metrics displayed in a SolarWinds Observability® dashboard view.

Metrics

Once you install and enable the Java APM library, it will start reporting the key performance metrics of your application that can be viewed in the Metrics Explorer. The agent collects three types of metrics:

1. Standard metrics

The APM library collects standard metrics for all requests from the application. They help you gain insight into the service’s response time and error rate. Some of the standard metrics include:

Metric	Description
trace.service.outbound_calls.database.query.response_time	The average response time for a database query.
trace.service.outbound_calls.cache.op.response_time	The average response time for a cache operation.
trace.service.outbound_calls.remote_service.call.response_time	The average response time for a remote service call.

You can find the comprehensive list of trace-derived metrics reported by the APM agent in the docs.

2. Trace-derived metrics

The APM agent provides a range of metrics based on adaptive sampling of outbound calls made by your application. These trace-derived metrics allow you to monitor the database, cache, remote services, and exception metrics. Some of the trace-derived metrics include:

Metric	Description
trace.service.outbound_calls.database.query.response_time	The average response time for a database query.
trace.service.outbound_calls.cache.op.response_time	The average response time for a cache operation.
trace.service.outbound_calls.remote_service.call.response_time	The average response time for a remote service call.

You can find the comprehensive list of trace-derived metrics reported by the APM agent in the docs.

3. Runtime metrics

Java runtime metrics are gathered from JMX MBeans and reported by the APM agent at a fixed interval. It reports metrics such as cumulative garbage collector values, memory, runtime, and threading details. You can find the comprehensive list of runtime metrics reported by the APM agent in the docs.

Integration with SolarWinds Observability

Integrating your Java application with SolarWinds Observability streamlines the monitoring of an application's services. SolarWinds Observability offers multiple capabilities to aid in instrumenting, monitoring, analyzing performance, and troubleshooting issues.

The Entity Explorer provides high-level information about all monitored entities. You can use the explorer to access details about your Java service, its health, and active alerts.

With the Metrics Explorer, you can view and analyze metrics, such as CPU and memory utilization, average response time, and error rate for the Java service. You can apply and save several filters, such as hostname, time range, or region.
You can use the Trace Explorer to trace the path of a single request through an application. With traces, you can gain insight into how requests travel across multiple hosts and services, view performance at each step of the request, and diagnose issues, such as latency or errors. This is extremely useful for understanding downstream and upstream service dependencies and ensuring your Java service runs smoothly.

Java trace details in a SolarWinds Observability®.

Getting Started with the SolarWinds Observability Java Agent

When you’re ready to use the Java agent, your first step is to sign up for the free trial version of SolarWinds Observability.

Create an API ingestion token

To create an API ingestion token, follow these steps:

Log into your SolarWinds Observability account.
Click Add Data at the top of the dashboard.
In the dialog that opens up, click Services.
Enter a name for the service, and choose Java as the language for your operating system.
Click Next, select Generate New Token, and enter an Ingestion Token Name.
Click Next to create the token.
Copy the token and keep it handy. We’ll use it in the following sections while configuring the Java agent.

Creating an API Ingestion token

Note: If you previously created an API token in your SolarWinds Observability account, then you can reuse your existing API token.

Install the library JAR

Before installing the Java library, check the supported platforms page to ensure your application runs on a system supported by SolarWinds Observability.

For this demonstration, we’ll install the library JAR on a Linux system. Navigate to the desired directory for installing the JAR, and download it by executing the following command:

curl -sSO https://agent-binaries.cloud.solarwinds.com/apm/java/latest/solarwinds-apm-agent.jar

Next, set the agent's service key by exporting the following environment variable:

export SW_APM_SERVICE_KEY=<YourServiceKey>

The service key uses this format: YourApiToken:YourServiceName. Replace YourApiToken with the API token you generated in the previous section, and replace YourServiceName with the name of the service you provided while creating the token.

Finally, set the agent's collector endpoint by setting the following environment variable:

export SW_APM_COLLECTOR=apm.collector.xx-yy.cloud.solarwinds.com

xx-yy is dependent on the URL that you use to access SolarWinds Observability. Find more information in this guide.

Note: If your application runs on a platform other than Linux, refer to the installation guide for platform-specific instructions.

Load the library to monitor the service

To load the Java APM agent library, add the following parameter to the JVM startup command:

-javaagent:<library installation path>/solarwinds-apm-agent.jar

You can find application server-specific instructions for loading the JAR in the Linux web servers guide.

After configuring the Java library, you will need to restart the JVM for the library to load and connect to the SolarWinds APM collector. Once the JVM has restarted, wait for the Java library to establish a successful connection. Once the library loads successfully, the “waiting for connection” button in SolarWinds Observability should change to OK.

Conclusion

The SolarWinds Observability Java APM agent offers full compatibility with OpenTelemetry and provides additional features for automatic tracing in JVM-based languages. It requires minimal configuration to start gathering metrics and provides several configuration options for customizing the metric collection and reporting. SolarWinds Observability seamlessly integrates the JVM-based services by providing multiple tools such as the Entity Explorer, Metrics Explorer, and Trace Explorer.