Docs » Collect application spans and traces » Instrument Java applications for Splunk Observability Cloud » Configure the Java agent for Splunk Observability Cloud

Configure the Java agent for Splunk Observability Cloud 🔗

You can configure the Java agent from the Splunk Distribution of OpenTelemetry Java to suit most of your instrumentation needs. In most cases, modifying the basic configuration is enough to get started. More advanced settings are also available.

The following sections describe all available settings for configuring the Java Virtual Machine (JVM) agent, including options for enabling new features that are unique to the Splunk Distribution of OpenTelemetry Java.

Configuration methods 🔗

You can change the agent settings in two ways:

  • Set an environment variable. For example:

    export OTEL_SERVICE_NAME=my-java-app
    
  • Add a system property as runtime parameter. For example:

    java -javaagent:./splunk-otel-javaagent.jar \
    -Dotel.service.name=<my-java-app> \
    -jar <myapp>.jar
    

Environment variables are the preferred way of configuring OpenTelemetry agents. System properties, if specified, override existing environment variables.

General settings 🔗

The following settings are specific to the Splunk Distribution of OpenTelemetry Java:

System property

Environment variable

Description

splunk.access.token

SPLUNK_ACCESS_TOKEN

Authentication token that lets exporters send data directly to Splunk Observability Cloud. Unset by default. Not required unless you need to send data to the Observability Cloud ingest endpoint. See Create and manage access tokens.

splunk.trace-response-header.enabled

SPLUNK_TRACE_RESPONSE_HEADER_ENABLED

Enables the addition of server trace information to HTTP response headers. For more information, see Server trace information. Default is true.

Trace configuration 🔗

The following settings control tracing limits and attributes:

System property

Environment variable

Description

otel.service.name

OTEL_SERVICE_NAME

Name of the service or application you’re instrumenting. Takes precedence over the service name defined in the OTEL_RESOURCE_ATTRIBUTES variable.

otel.resource.attributes

OTEL_RESOURCE_ATTRIBUTES

Comma-separated list of resource attributes added to every reported span. For example, key1=val1,key2=val2.

otel.instrumentation.common.peer-service-mapping

OTEL_INSTRUMENTATION_COMMON_PEER_SERVICE_MAPPING

Used to add a peer.service attribute by specifying a comma-separated list of mapping from hostnames or IP addresses. For example, if set to 1.2.3.4=cats-service,dogs-service.serverlessapis.com=dogs-api, requests to 1.2.3.4 have a peer.service attribute of cats-service and requests to dogs-service.serverlessapis.com have one of dogs-api.

otel.instrumentation.methods.include

OTEL_INSTRUMENTATION_METHODS_INCLUDE

Adds @WithSpan annotation functionality for the target method string. Format is my.package.MyClass1[method1,method2];my.package.MyClass2[method3].

otel.instrumentation.opentelemetry-annotations.exclude-methods

OTEL_INSTRUMENTATION_OPENTELEMETRY_ANNOTATIONS_EXCLUDE_METHODS

Suppresses @WithSpan instrumentation for specific methods. Format is my.package.MyClass1[method1,method2];my.package.MyClass2[method3].

otel.span.attribute.count.limit

OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT

Maximum number of attributes per span. Default is unlimited.

otel.span.event.count.limit

OTEL_SPAN_EVENT_COUNT_LIMIT

Maximum number of events per span. Default is unlimited.

otel.span.link.count.limit

OTEL_SPAN_LINK_COUNT_LIMIT

Maximum number of links per span. Default is 1000.

Exporters configuration 🔗

The following settings control trace exporters and their endpoints:

System property

Environment variable

Description

otel.traces.exporter

OTEL_TRACES_EXPORTER

Traces exporter to use. You can set multiple comma-separated values. For example, otlp,console_span. Default is otlp. To select the Jaeger exporter, use jaeger-thrift-splunk.

otel.exporter.otlp.endpoint

OTEL_EXPORTER_OTLP_ENDPOINT

OTLP gRPC endpoint. Default is http://localhost:4317.

otel.exporter.jaeger.endpoint

OTEL_EXPORTER_JAEGER_ENDPOINT

Jaeger endpoint. Default is http://localhost:9080/v1/trace.

The Splunk Distribution of OpenTelemetry Java uses the OTLP gRPC span exporter by default. If you’re still using the Smart Agent, or need to send traces directly to the Splunk ingest API endpoint, use the Jaeger exporter.

For example, the following export statements configure the agent to export data to the Splunk ingest API endpoint through Jaeger:

export SPLUNK_ACCESS_TOKEN=<access_token>
export OTEL_TRACES_EXPORTER=jaeger-thrift-splunk
export OTEL_EXPORTER_JAEGER_ENDPOINT=https://ingest.<realm>.signalfx.com/v2/trace

To obtain an access token, see Create and manage user API access tokens.

In the ingest endpoint URL, realm is the O11y realm. For example, us0. To find the realm of your account, open the main menu in Observability Cloud, hover over your user name, and then select Accounts Settings.

Propagators configuration 🔗

The following settings control trace propagation:

System property

Environment variable

Description

otel.propagators

OTEL_PROPAGATORS

Comma-separated list of propagators you want to use. Default is tracecontext,baggage. You can find the list of supported propagators in the OpenTelemetry documentation.

For backward compatibility with older versions of the Splunk Distribution of OpenTelemetry Java or the SignalFx Java Agent, use the b3multi trace propagator:

export OTEL_PROPAGATORS=b3multi

Server trace information 🔗

To connect Real User Monitoring (RUM) requests from mobile and web applications with server trace data, enable Splunk trace response headers by setting the following environment variable:

export SPLUNK_TRACE_RESPONSE_HEADER_ENABLED=true

When you set this environment variable, your application instrumentation adds the following response headers to HTTP responses:

Access-Control-Expose-Headers: Server-Timing
Server-Timing: traceparent;desc="00-<serverTraceId>-<serverSpanId>-01"

The Server-Timing header contains the traceId and spanId parameters in traceparent format. See the following W3C documents for more information about the Server-Timing header:

The following server frameworks and libraries add Server-Timing information:

  • Servlet API 2.2-4.X. 5.0+ is not supported yet.

  • Netty 3.8-4.0. 4.1+ is not supported yet.

Metrics settings 🔗

The following settings control metrics collection for the Java agent:

System property

Environment variable

Description

splunk.metrics.enabled

SPLUNK_METRICS_ENABLED

Enables exporting metrics. See Metrics and attributes collected by the Splunk OTel Java agent for more information. Default is false.

splunk.metrics.endpoint

SPLUNK_METRICS_ENDPOINT

The OTel connector metrics endpoint. Default is http://localhost:9943.

splunk.metrics.export.interval

SPLUNK_METRICS_EXPORT_INTERVAL

Interval between pushing metrics. You can define duration in the form <number><unit>, where the unit can be ms, s, m, h, or d. The default interval is 30s. If you enter a number but not a unit, the default unit is assumed to be ms.

To configure the export to send metrics directly to Splunk ingest API, set the splunk.access.token and splunk.metrics.endpoint properties. For example:

export SPLUNK_ACCESS_TOKEN=:<admin-api-access-tokens>
export SPLUNK_METRICS_ENDPOINT=https://ingest.<realm>.signalfx.com

To obtain an access token, see Create and manage user API access tokens.

In the ingest endpoint URL, realm is the O11y realm. For example, us0. To find the realm of your account, open the main menu in Observability Cloud, hover over your user name, and then select Accounts Settings.

Note

Metric support is experimental.

Other settings 🔗

System property

Environment variable

Description

otel.javaagent.enabled

OTEL_JAVAAGENT_ENABLED

Globally enables the Java agent automatic instrumentation. Default is true. Useful for disabling auto instrumentation in testing scenarios or pipelines.