Docs » Instrument back-end applications to send spans to Splunk APM » Instrument Java applications for Splunk Observability Cloud » Instrument a Java application for Splunk Observability Cloud

Instrument a 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:

  1. Log in to Observability Cloud.

  2. Open the Java guided setup. Optionally, you can navigate to the guided setup on your own:

    1. In the left navigation menu, select Data Management.

    2. Select Add Integration to open the Integrate Your Data page.

    3. In the integration filter menu, select By Product.

    4. Select the APM product.

    5. Select the Java tile to open the Java guided setup.

Install and enable the Java agent 🔗

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

  1. Check that you meet the requirements. See Java agent compatibility and requirements.

  2. 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
    
  3. Set the OTEL_SERVICE_NAME environment variable:

    export OTEL_SERVICE_NAME=<yourServiceName>
    
  4. (Optional) Set the endpoint URL if the Splunk Distribution of OpenTelemetry Collector is running on a different host:

    export OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>
    
  5. (Optional) Set the deployment environment and service version:

    export OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'
    
  6. Set the -javaagent argument to the path of the Java agent:

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

    Note

    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 Observability > 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.

Enable metrics collection 🔗

To enable automatic metric collection, enable 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.

Note

If you enable memory profiling, metrics collection is enabled automatically and cannot be disabled.

Enable AlwaysOn Profiling 🔗

To enable AlwaysOn CPU 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.

java -javaagent:./splunk-otel-javaagent.jar \
-Dsplunk.profiler.enabled=true \
-jar <myapp>.jar

To enable memory profiling, set the splunk.profiler.memory.enabled system property or the SPLUNK_PROFILER_MEMORY_ENABLED environment variable to true after enabling CPU profiling.

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 drop rules.

In the following example, the sampler drops all SERVER spans whose endpoints match healtcheck, and sends the rest of spans using the fallback sampler, parentbased_always_on:

export OTEL_TRACES_SAMPLER=rules
export OTEL_TRACES_SAMPLER_ARG=drop=/healthcheck;fallback=parentbased_always_on

See Samplers configuration for more information.

Deploy the Java agent in Kubernetes 🔗

To deploy the Java agent in Kubernetes, 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 .spec.template.spec.containers.env section:

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>"

Deploy the Java agent in Docker 🔗

To deploy the Java agent in Docker, 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-all.jar","-jar","./<myapp>.jar"]

Use ENV commands to set environment variables for the Java agent. To enable metrics or profiling, add the required -Dotel argument to the ENTRYPOINT list.

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 enabling custom sampling, see Configure the Java agent for Splunk Observability Cloud.

Send data directly to Observability Cloud 🔗

By default, all telemetry is sent to the local instance of the Splunk Distribution of OpenTelemetry Collector.

If you need to send data directly to 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 Observability Cloud realm, for example, us0. To find the realm name of your account, follow these steps:

  1. Open the left navigation menu in Observability Cloud.

  2. Select Settings.

  3. Select your username.

The realm name appears in the Organizations section.

Note

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.