Documentation forSolarWinds Observability SaaS

Java Library instrumentation SDK

The SolarWinds Observability Java Library is a distribution of the OpenTelemetry Java agent. Use the OpenTelemetry Java SDK to add manual instrumentation in addition to the automatic instrumentation provided by the agent. The SolarWinds Observability Java Library also provides a custom SDK to access additional features provided by our distribution. Both SDKs can be used with the SolarWinds Observability Java Library.

The custom SDK is complementary and does not package any features provided by the OpenTelemetry Java SDK. The two SDKs can be used together in the same project.

Get started with the OTel Java SDK

Add the opentelemetry-api dependency

Add the following dependency to your project’s pom.xml (for maven) or build.gradle (for gradle) file. Replace x.x.x with the version number of the OTel agent bundled with the Java Library.

The most recent Java Library (  ) is based on the Java OTel agent version   . For older releases, see the release notes for the installed version of your Java Library or look for the INFO level log message [SolarWinds APM] Otel agent version: to determine the correct OTel agent version number.

Maven

<dependencies>
  ...
  <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>x.x.x</version>
      <scope>provided</scope>
  </dependency>
  ...
</dependencies>

Gradle

dependencies {
    ...
	runtimeOnly 'io.opentelemetry:opentelemetry-api:x.x.x'
	...
}

Use the OTel Java SDK

Acquire the global OpenTelemery Object

To add your instrumentation, acquire the OpenTelemetry object created by auto-instrumentation using the following code.

OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();

Acquire a Tracer

Once you’ve acquired the OpenTelemetry object, get a tracer from the OpenTelemetry object using the following code.

Tracer tracer = openTelemetry.getTracer("instrumentation-library-name", "1.0.0");

Create a span

Once you’ve acquired a Tracer object, create a span using the following code.

Span span = tracer.spanBuilder("span-name").startSpan();
try (Scope ss = span.makeCurrent()) {
  // do something
} finally {
    span.end();
}

Call the makeCurrent method on the created span so subsequently created spans can be linked. The try-with-resources statement is used because the Scope is a resource that must be closed. If it is not closed, your resource may leak and the trace may never end. The finally block is needed to end the Span so it can be exported if sampled, regardless of any exception.

Complete Code

OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
Tracer tracer = openTelemetry.getTracer("instrumentation-library-name", "1.0.0");
Span span = tracer.spanBuilder("span-name").startSpan();
try (Scope ss = span.makeCurrent()) {
  // do something
} finally {
    span.end();
}

For additional information, see Manual Instrumentation in the OpenTelemetry documentation. Do not follow the instructions for setting up the OpenTelemetrySdk , since this is already set up by the automatic instrumentation. Instead, acquire the globally configured OpenTelemetry object using the instructions on this page, then continue with the instructions in Acquiring a Tracer. If you prefer to use annotations, see Using instrumentation annotations with a Java agent.

Get started with the SolarWinds Observability custom Java SDK

Access additional features with the custom SolarWinds Observability SDK for the Java Library.

Add the custom SDK

Add the following dependency to your project’s pom.xml (for maven) or build.gradle (for gradle) file. Replace x.x.x with the version of the Java SDK you intend to use. The SDK is versioned together with the Java Library. SolarWinds recommends you use the same version as your library.

The most recent Java Library and custom SDK version and release date is   .

Maven

<dependency>
  <groupId>io.github.appoptics</groupId>
  <artifactId>solarwinds-otel-sdk</artifactId>
  <version>x.xx.x</version>
</dependency>

Gradle

implementation 'io.github.appoptics:solarwinds-otel-sdk:x.xx.x'

Use the custom SDK

The SDK currently provides the following features:

  • Custom transaction naming.
  • Library initialization hooks, to wait for the library to complete initialization.

Set a transaction name for the current trace

The Java Library custom distribution assigns a transaction name based on a URL, a Controller/Action, or other detected framework information. The custom SDK provides the ability to override the transaction name so you can better describe the instrumented operation. When a custom transaction name is defined, the transaction name is converted to lowercase, longer transaction names are truncated, and invalid characters in the name are replaced. Transaction names that are empty strings or null values are considered invalid transaction name values and are ignored.

If multiple transaction names are set for the same trace, the last transaction name is used.

String transaction = "my custom transaction name";
SolarwindsAgent.setTransactionName(transactionName);

Alternatively, you can use configurable transaction naming to specify the span attributes to be used to form the transaction name.

Wait for the agent to finish initializing

The Java Library custom distribution must establish a connection with the collector and retrieve settings before requests can be sampled for tracing. When a single execution job is traced, SolarWinds recommends you include a short wait with the SolarwindsAgent.waitUntilReady method. This wait ensures the initialization is complete; otherwise trace data will not be exported. When SolarwindsAgent.waitUntilReady is used, the call is blocked until either the agent is ready or the wait timeout has elapsed.

OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
Tracer tracer = openTelemetry.getTracer("instrumentation-library-name", "1.0.0");

// wait for agent readiness
long timeout = 120;
SolarwindsAgent.waitUntilReady(timeout, TimeUnit.SECONDS);

// start tracing
Span span = tracer.spanBuilder("my-job").startSpan();
try (Scope ss = span.makeCurrent()) {
  // ... job execution here
} finally {
    span.end();
}

More information

More information about the SolarWinds Observability SaaS Java Library SDK can be found here.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.