Instrument your Java application for Splunk Observability Cloud 🔗
The Java agent from the Splunk Distribution of OpenTelemetry Java can automatically instrument your Java application by injecting instrumentation to Java classes. To get started, use the guided setup or follow the instructions manually.
Generate customized instructions using the guided setup 🔗
To generate all the basic installation commands for your environment and application, use the Java guided setup. To access the Java guided setup, follow these steps:
Log in to Splunk Observability Cloud.
Open the Java guided setup . Optionally, you can navigate to the guided setup on your own:
In the navigation menu, select.
Select Add Integration to open the Integrate Your Data page.
In the integration filter menu, select By Product.
Select the APM product.
Select the Java tile to open the Java guided setup.
Install the Splunk Distribution of OpenTelemetry Java manually 🔗
Follow these instructions to install the Splunk Distribution of OpenTelemetry Java:
Install and activate the Java agent 🔗
Follow these steps to automatically instrument your application using the Java agent:
Check that you meet the requirements. See Java agent compatibility and requirements.
Download the JAR file for the latest version of the agent:
curl -L https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar \ -o splunk-otel-javaagent.jar
Invoke-WebRequest -Uri https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar -OutFile splunk-otel-javaagent.jar
(Optional) Set the endpoint URL if the Splunk Distribution of OpenTelemetry Collector is running on a different host:
(Optional) Set the deployment environment and service version:
-javaagentargument to the path of the Java agent:
java -javaagent:./splunk-otel-javaagent.jar -jar <myapp>.jar
If your application runs on a supported Java server, see Define agent paths for Java application servers for Splunk Observability Cloud.
If no data appears in APM, see Troubleshoot Java instrumentation for Splunk Observability Cloud.
If you need to add custom attributes to spans or want to manually generate spans, instrument your Java application or service manually. See Manually instrument Java applications for Splunk Observability Cloud.
Activate AlwaysOn Profiling 🔗
To activate AlwaysOn Profiling, use the following system property argument. You can also use the
SPLUNK_PROFILER_ENABLED environment variable. For more information, see Introduction to AlwaysOn Profiling for Splunk APM.
To activate memory profiling, set the
splunk.profiler.memory.enabled system property or the
SPLUNK_PROFILER_MEMORY_ENABLED environment variable to
true after activating AlwaysOn Profiling.
The following example shows how to activate the profiler using the system property:
java -javaagent:./splunk-otel-javaagent.jar \ -Dsplunk.profiler.enabled=true \ -Dsplunk.profiler.memory.enabled=true \ -Dotel.exporter.otlp.endpoint=http(s)://collector:4317 \ -Dsplunk.metrics.endpoint=http(s)://collector:9943 -jar <your_application>.jar
Activate metrics collection 🔗
To activate automatic metric collection, activate the metrics feature using a system property argument. You can also use the
SPLUNK_METRICS_ENABLED environment variable.
java -javaagent:./splunk-otel-javaagent.jar \ -Dsplunk.metrics.enabled=true \ -jar <myapp>.jar
If your metrics endpoint is different than the default value, set the
SPLUNK_METRICS_ENDPOINT environment variable. See Metrics collection settings for more information.
If you activate memory profiling, metrics collection is activated automatically and cannot be deactivated.
Ignore specific endpoints 🔗
By default, the Java agent collects traces from all the endpoints of your application. To ignore specific endpoints, use the
rules sampler and define
In the following example, the sampler drops all
SERVER spans whose endpoints match
healtcheck, and sends the rest of spans using the fallback sampler,
export OTEL_TRACES_SAMPLER=rules export OTEL_TRACES_SAMPLER_ARG=drop=/healthcheck;fallback=parentbased_always_on
See Samplers configuration for more information.
Configure the Java agent 🔗
You can configure the agent using environment variables or by setting system properties as runtime arguments. For more details about both methods, see Configuration methods.
For advanced configuration of the JVM agent, like changing trace propagation formats, correlating traces and logs, or activating custom sampling, see Configure the Java agent for Splunk Observability Cloud.
Deploy the Java agent in Kubernetes 🔗
To deploy the Java agent in Kubernetes, follow these steps:
Deploy the Java agent in Docker 🔗
To deploy the Java agent in Docker, do the following:
Edit the Dockerfile for your application image to add the following commands:
# Adds the latest version of the Splunk Java agent ADD https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent.jar . # Modifies the entry point ENTRYPOINT ["java","-javaagent:splunk-otel-javaagent.jar","-jar","./<myapp>.jar"]
ENVcommands to set environment variables for the Java agent. To activate metrics or profiling, add the required
-Dotelargument to the
When you deploy the Java agent with your application build, you ensure that the Java agent is launched with tracing.
Configure Kubernetes to run the agent 🔗
To configure your application in Kubernetes to use the Java agent, configure the Kubernetes Downward API to expose environment variables to Kubernetes resources.
The following example shows how to update a deployment to expose environment variables by adding the agent configuration under the
apiVersion: apps/v1 kind: Deployment spec: selector: matchLabels: app: your-application template: spec: containers: - name: myapp env: - name: SPLUNK_OTEL_AGENT valueFrom: fieldRef: fieldPath: status.hostIP - name: OTEL_EXPORTER_OTLP_ENDPOINT value: "http://$(SPLUNK_OTEL_AGENT):4317" - name: OTEL_SERVICE_NAME value: "<serviceName>" - name: OTEL_RESOURCE_ATTRIBUTES value: "deployment.environment=<environmentName>"
You can also deploy instrumentation using the Kubernetes Operator. See Install the Collector and the upstream Kubernetes Operator for Auto Instrumentation.
Send data directly to Splunk Observability Cloud 🔗
By default, the agent sends all telemetry to the local instance of the Splunk Distribution of OpenTelemetry Collector.
If you need to send data directly to Splunk Observability Cloud, set the following environment variables:
export SPLUNK_ACCESS_TOKEN=<access_token> export SPLUNK_REALM=<realm>
To obtain an access token, see Retrieve and manage user API access tokens using Splunk Observability Cloud.
In the ingest endpoint URL,
realm is the Splunk Observability Cloud realm, for example,
us0. To find the realm name of your account, follow these steps:
Open the navigation menu in Splunk Observability Cloud.
Select your username.
The realm name appears in the Organizations section.
For more information on the ingest API endpoints, see Send APM traces .
This procedure applies to spans and traces. To send AlwaysOn Profiling data, you must use the OTel Collector.
Instrument Lambda functions 🔗
You can instrument AWS Lambda functions using the Splunk OpenTelemetry Lambda Layer. See Instrument your AWS Lambda function for Splunk Observability Cloud for more information.
Upgrade the Splunk Distribution of OpenTelemetry Java 🔗
New releases of the Splunk Distribution of OpenTelemetry Java happen after a new upstream release, or when new features and enhancements are available.
Upgrade to each new version of the Splunk Distribution of OpenTelemetry Java after it’s released. To find out about new releases, watch the GitHub repository at https://github.com/signalfx/splunk-otel-java/releases
See the versioning document in GitHub to learn more about version numbers. Major versions contain a large number of changes, which might result in increased risk to your production environment. Minor version changes indicate common releases, which contain a modest number of changes Patch releases are infrequent and contain specific fixes or enhancements.
Best practices for upgrades 🔗
To reduce the risk of issues with an upgrade, do the following:
See the release notes and changelog for each release to determine if the release has changes that might affect your environment. Pay attention to mentions of libraries, frameworks, and tools that your software uses.
Never put untested code into production. Verify that the new build works in a staging or pre-production environment before promoting it to production. Don’t use snapshot builds in production.
Use canary instances. Let the canaries operate with the code before releasing the code to production. Run the canaries for at least a few hours, and preferably for a few days.
Minimize the number of dependencies, including instrumentation, that change in a given release. Determining the root cause of a problem after upgrading multiple dependencies at the same time can be difficult.
Pin version numbers in your build pipeline. Don’t use the
latestURL in automated processes.