Caution
The Splunk Distribution of OpenTelemetry Java version 1.x is deprecated as of June 25, 2024 and will reach End of Support on June 30, 2025. Until then, only critical security fixes and bug fixes will be provided.
New customers should use the latest version of the Splunk Distribution of OpenTelemetry Java. Existing customers should consider migrating to version 2.5.0 or higher. To learn how to migrate, see Migration guide for OpenTelemetry Java 2.x metrics.
Configure the Java agent 1.x for Splunk Observability Cloud (Deprecated) π
The following sections describe all available settings for configuring the Java agent 1.x, including options for activating 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
$env: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:
Environment variable |
Description |
---|---|
|
The name of your organizationβs realm, for example, |
|
A Splunk 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 Splunk Observability Cloud ingest endpoint. See Create and manage authentication tokens using Splunk Observability Cloud. |
|
Activates the addition of server trace information to HTTP response headers. For more information, see Server trace information. The default value is |
|
Adds the full command line as a resource attribute for all metrics. If false, commands longer than 255 characters are truncated. |
Trace configuration π
The following settings control tracing limits and attributes:
Environment variable |
Description |
---|---|
|
Name of the service or application youβre instrumenting. Takes precedence over the service name defined in the |
|
Comma-separated list of resource attributes added to every reported span. For example, |
|
Used to add a |
|
Adds |
|
Suppresses |
|
Maximum number of attributes per span. The default value is unlimited. |
|
Maximum number of events per span. The default value is unlimited. |
|
Maximum number of links per span. The default value is |
Exporters configuration π
The following settings control trace exporters and their endpoints:
Environment variable |
Description |
---|---|
|
Trace exporter to use. You can set multiple comma-separated values. |
|
OTLP gRPC endpoint. The default value is |
The Splunk Distribution of OpenTelemetry Java uses the OTLP gRPC span exporter by default. To send data directly to Splunk Observability Cloud, see Send data directly to Splunk Observability Cloud.
Samplers configuration π
The following settings control trace sampling:
Environment variable |
Description |
---|---|
|
Sampler to use. The default value is
|
|
Semicolon-separated list of rules for the
If you donβt set arguments when using the |
Example of trace sampling π
The following example shows how to use the rules
traces sampler to exclude the /healthcheck
endpoint from monitoring:
export OTEL_TRACES_SAMPLER=rules
export OTEL_TRACES_SAMPLER_ARG=drop=/healthcheck;fallback=parentbased_always_on
All requests to downstream services that happen as a consequence of calling an excluded endpoint are also excluded.
Propagators configuration π
The following settings control trace propagation:
Environment variable |
Description |
---|---|
|
Comma-separated list of propagators you want to use. The default value is |
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
$env:OTEL_PROPAGATORS=b3multi
Java settings for AlwaysOn Profiling π
The following settings control the AlwaysOn Profiling feature for the Java agent:
Environment variable |
Description |
---|---|
|
Activates AlwaysOn Profiling. The default value is |
|
The collector endpoint for profiler logs. By default, it takes the value of |
|
The location of the JDK Flight Recorder files. The default value is the local directory ( |
|
The duration of the recording unit. You can define duration in the form |
|
Whether to preserve JDK Flight Recorder (JFR) files or not. The default value is |
|
Frequency with which call stacks are sampled, in milliseconds. The default value is 10000 milliseconds. |
|
Note OpenJDK versions 15.0 to 17.0.8, are not supported for memory profiling. See https://bugs.openjdk.org/browse/JDK-8309862 in the JDK bug system for more information. System property: |
|
Rate limit for memory profiling data, expressed as stack traces per unit of time. You can define duration in the form |
|
Whether to activate TLAB memory events. The default value is the value assigned to the |
|
Whether to include stack traces of the agent internal threads and stack traces with JDK internal frames. The default value is |
|
Whether to include only stack traces that are linked to a span context. The default value is |
For more information on AlwaysOn Profiling, see Introduction to AlwaysOn Profiling for Splunk APM.
Metrics collection settings π
Note
To migrate from OpenTelemetry native metrics, see Migration guide for OpenTelemetry Java 2.x metrics.
The following settings control metrics collection for the Java agent:
Environment variable |
Description |
---|---|
|
System property: |
|
The OTel collector metrics endpoint. Default is |
|
Deprecated. Use |
Server trace information π
To connect Real User Monitoring (RUM) requests from mobile and web applications with server trace data, trace response headers are activated by default. The 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. For more information, see the Server-Timing and traceparent documentation on the W3C website.
The following server frameworks and libraries add Server-Timing
information:
Servlet API versions 2.2 to 4.X.
Netty versions 3.8 to 4.0.
Note
If you need to deactivate trace response headers, set SPLUNK_TRACE_RESPONSE_HEADER_ENABLED
to false
.
Other settings π
Environment variable |
Description |
---|---|
|
Globally activates the Java agent automatic instrumentation. The default value is |