Get Started   •   Get Involved   •   Migrate from SignalFx Java Agent

Examples   •   About the distribution   •   Security   •   Supported Libraries   •   Troubleshooting

Splunk Distribution of OpenTelemetry Java

The Splunk Distribution of OpenTelemetry Instrumentation for Java provides a Java Virtual Machine (JVM) agent that automatically instruments your Java application to capture and report distributed traces to Splunk APM.

This distribution comes with the following defaults:

• W3C tracecontext and W3C baggage context propagation; B3 can also be configured.
• OTLP gRPC exporter configured to send spans to a locally running Splunk OpenTelemetry Connector (http://localhost:4317); Jaeger Thrift exporter available for Smart Agent (http://localhost:9080/v1/trace).
• Unlimited default limits for configuration options to support full-fidelity traces.

If you're currently using the SignalFx Java Agent and want to migrate to the Splunk Distribution of OpenTelemetry Java, see Migrate from the SignalFx Java Agent.

The following documentation refers to the in-development version of splunk-otel-java. Docs for the latest version (v1.9.0) can be found here.

Requirements

The agent works with Java runtimes version 8 and higher. For the full list of requirements and supported libraries and versions, see Requirements for the Java agent in the official Splunk documentation.

Get started

Follow these steps to automatically instrument your application using the Java agent:

1. Check that you meet the requirements.

2. Make sure that the collector you set up to receive trace data is installed and configured.

3. Download the JAR file for the latest version of the agent:

   • On Linux, run:

     curl -L https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar \
     -o splunk-otel-javaagent.jar

   • On Windows (PowerShell), run:

     Invoke-WebRequest -Uri https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar -OutFile splunk-otel-javaagent.jar

4. Set the OTEL_SERVICE_NAME environment variable:

   • On Linux, run:

     export OTEL_SERVICE_NAME=<yourServiceName>

   • On Windows (PowerShell), run:

     $env:OTEL_SERVICE_NAME=<yourServiceName>

5. Enable the Java agent:

   java -javaagent:./splunk-otel-javaagent.jar \
     -jar <myapp>.jar

   Insert the -javaagent flag before the -jar file, adding it as a JVM option, not as an application argument.

Note: Supported java servers may require different steps to add the path to the JVM agent to their configuration. See Add the JVM agent to Java servers.

Tip: To generate a snippet that includes all the basic install commands for your environment and service, open the Splunk Observability Cloud wizard in Data Setup > APM Instrumentation > Java > Add Connection.

When you run your application with the Java agent, trace data goes to Observability Cloud through the Splunk OTel connector. If no data appears in Observability > APM, see Troubleshooting.

For full install instructions, including K8s and Lambda snippets, see Instrument Java services for Observability Cloud in the official Splunk documentation.

To see the Java Agent in action with sample applications, see our examples.

Advanced configuration

To fully configure the agent of the Splunk Distribution of OpenTelemetry Java, see Configure the Java agent in the official Splunk documentation.

Correlating traces with logs

The Splunk Distribution of OpenTelemetry Java provides a way to correlate traces with logs. For more information see Connect Java application trace data with logs in the official Splunk documentation.

Manually instrument a Java application

Documentation on how to manually instrument a Java application is available in the OpenTelemetry official documentation. To learn how to add custom metrics to your application please consult our docs.

To extend the instrumentation with the OpenTelemetry Instrumentation for Java, you have to use a compatible API version.

The Splunk Distribution of OpenTelemetry Java version 1.9.1 is compatible with:

• OpenTelemetry API version 1.12.0
• OpenTelemetry Instrumentation for Java version 1.12.1
• Micrometer version 1.8.4

Snapshot builds

We publish snapshot builds with every merge to the main branch. Snapshots are primarily intended to test new functionality and are not recommended for production use.

Troubleshooting

For troubleshooting information and known issues, see Troubleshooting Java instrumentation in the official Splunk documentation.

License and versioning

The Splunk Distribution of OpenTelemetry Java is a distribution of the OpenTelemetry Instrumentation for Java project. It is released under the terms of the Apache Software License version 2.0. For more details, see the license file.

ℹ️  SignalFx was acquired by Splunk in October 2019. See Splunk SignalFx for more information.