Configuration

The OpenTelemetry SDK provides a working implementation of the API, and can be set up and configured in a number of ways. The Java SDK supports most of the available configuration options. For conformance details, see the compliance matrix.

The following configuration options apply to the Java agent and all other uses of the SDK.

General

The autoconfigure module (opentelemetry-sdk-extension-autoconfigure) allows you to automatically configure the OpenTelemetry SDK based on a standard set of supported environment variables and system properties. Start your SDK configurations from it.

Disabling OpenTelemetrySdk

The OpenTelemetry SDK can be disabled entirely. If disabled, AutoConfiguredOpenTelemetrySdk#getOpenTelemetrySdk() will return a minimally configured instance (i.e. OpenTelemetrySdk.builder().build()).

System propertyDescriptionDefault
otel.sdk.disabledIf true, disable the OpenTelemetry SDK.false

Resources

A resource is the immutable representation of the entity producing the telemetry. See resources for more details.

System PropertyDescription
otel.resource.attributesSpecify resource attributes in the following format: key1=val1,key2=val2,key3=val3.
otel.service.nameSpecify logical service name. Takes precedence over service.name defined with otel.resource.attributes.
otel.experimental.resource.disabled-keysSpecify resource attribute keys that are filtered.

Make sure to use otel.service.name to set the service.name resource attribute, which represents the logical name of your service. If unspecified, the SDK sets service.name=unknown_service:java by default.

ResourceProvider SPI

The autoconfigure-spi SDK extension provides a ResourceProvider SPI that allows libraries to automatically provide resources, which are merged into a single resource by the autoconfiguration module. You can create your own ResourceProvider, or optionally use an artifact that includes built-in ResourceProviders:

Disabling automatic ResourceProviders

Many instrumentation agent distributions automatically include various ResourceProvider implementations. These can be turned on or off as follows:

Environment variableDescription
otel.java.enabled.resource.providersTurns on one or more ResourceProvider types. If unset, all resource providers are enabled.
otel.java.disabled.resource.providersTurns off one or more ResourceProvider types.

The value for these properties must be a comma-separated list of fully qualified ResourceProvider class names. For example, if you don’t want to expose the name of the operating system through the resource, you can pass the following JVM argument:

-Dotel.java.disabled.resource.providers=io.opentelemetry.instrumentation.resources.OsResourceProvider

Attribute limits

The following properties can be used to control the maximum number and length of attributes.

System propertyDescriptionDefault
otel.attribute.value.length.limitThe maximum length of attribute values. Applies to spans and logs.No limit
otel.attribute.count.limitThe maximum number of attributes. Applies to spans, span events, span links, and logs.128

Propagators

Propagators determine which distributed tracing header formats are used, and which baggage propagation header formats are used.

System propertyDescriptionDefault
otel.propagatorsThe propagators to be used. Use a comma-separated list for multiple propagators.tracecontext,baggage (W3C)

Supported values are the following:

ValueDescriptionArtifacts
tracecontextW3C Trace Context (add baggage as well to include W3C baggage).opentelemetry-api
baggageW3C Baggage.opentelemetry-api
b3B3 Single.opentelemetry-extension-tracepropagators
b3multiB3 Multi.opentelemetry-extension-tracepropagators
jaegerJaeger (includes Jaeger baggage).opentelemetry-extension-tracepropagators
xrayAWS X-Ray.io.opentelemetry.contrib:opentelemetry-aws-xray-propagator
ottraceOT Trace.opentelemetry-extension-trace-propagators

Exporters

These configuration options apply when using opentelemetry-exporter-{SDK exporter} artifacts (see list of available exporters).

Exporters output the telemetry. The following configuration properties are common to all exporters:

System propertyPurpose
otel.{signal}.exporterList of exporters to be used for {signal}, separated by commas. Default is otlp. none means no auto-configured exporter.
otel.java.experimental.exporter.memory_modeIf reusable_data, enable reusable memory mode (on exporters which support it) to reduce allocations. Default is immutable_data. This option is experimental and subject to change or removal.1

OTLP exporter (span, metric, and log exporters)

The OpenTelemetry Protocol (OTLP) span, metric, and log exporters.

System propertyDescriptionDefault
otel.{signal}.exporterSelect the OpenTelemetry exporter for {signal}.otlp
otel.exporter.otlp.endpointThe OTLP traces, metrics, and logs endpoint to connect to. Must be a URL with a scheme of either http or https based on the use of TLS. If protocol is http/protobuf the version and signal will be appended to the path (e.g. v1/traces, v1/metrics, or v1/logs).http://localhost:4317 when protocol is grpc, and http://localhost:4318/v1/{signal} when protocol is http/protobuf.
otel.exporter.otlp.{signal}.endpointThe OTLP {signal} endpoint to connect to. Must be a URL with a scheme of either http or https based on the use of TLS.http://localhost:4317 when protocol is grpc, and http://localhost:4318/v1/{signal} when protocol is http/protobuf.
otel.exporter.otlp.certificateThe path to the file containing trusted certificates to use when verifying an OTLP trace, metric, or log server’s TLS credentials. The file should contain one or more X.509 certificates in PEM format.The host platform’s trusted root certificates are used.
otel.exporter.otlp.{signal}.certificateThe path to the file containing trusted certificates to use when verifying an OTLP {signal} server’s TLS credentials. The file should contain one or more X.509 certificates in PEM format.The host platform’s trusted root certificates are used
otel.exporter.otlp.client.keyThe path to the file containing private client key to use when verifying an OTLP trace, metric, or log client’s TLS credentials. The file should contain one private key PKCS8 PEM format.No client key file is used.
otel.exporter.otlp.{signal}.client.keyThe path to the file containing private client key to use when verifying an OTLP {signal} client’s TLS credentials. The file should contain one private key PKCS8 PEM format.No client key file is used.
otel.exporter.otlp.client.certificateThe path to the file containing trusted certificates to use when verifying an OTLP trace, metric, or log client’s TLS credentials. The file should contain one or more X.509 certificates in PEM format.No chain file is used.
otel.exporter.otlp.{signal}.client.certificateThe path to the file containing trusted certificates to use when verifying an OTLP {signal} server’s TLS credentials. The file should contain one or more X.509 certificates in PEM format.No chain file is used.
otel.exporter.otlp.headersKey-value pairs separated by commas to pass as request headers on OTLP trace, metric, and log requests.
otel.exporter.otlp.{signal}.headersKey-value pairs separated by commas to pass as request headers on OTLP {signal} requests.
otel.exporter.otlp.compressionThe compression type to use on OTLP trace, metric, and log requests. Options include gzip.No compression will be used.
otel.exporter.otlp.{signal}.compressionThe compression type to use on OTLP {signal} requests. Options include gzip.No compression will be used.
otel.exporter.otlp.timeoutThe maximum waiting time, in milliseconds, allowed to send each OTLP trace, metric, and log batch.10000
otel.exporter.otlp.{signal}.timeoutThe maximum waiting time, in milliseconds, allowed to send each OTLP {signal} batch.10000
otel.exporter.otlp.protocolThe transport protocol to use on OTLP trace, metric, and log requests. Options include grpc and http/protobuf.grpc 2
otel.exporter.otlp.{signal}.protocolThe transport protocol to use on OTLP {signal} requests. Options include grpc and http/protobuf.grpc 2
otel.exporter.otlp.metrics.temporality.preferenceThe preferred output aggregation temporality. Options include DELTA, LOWMEMORY, and CUMULATIVE. If CUMULATIVE, all instruments will have cumulative temporality. If DELTA, counter (sync and async) and histograms will be delta, up down counters (sync and async) will be cumulative. If LOWMEMORY, sync counter and histograms will be delta, async counter and up down counters (sync and async) will be cumulative.CUMULATIVE
otel.exporter.otlp.metrics.default.histogram.aggregationThe preferred default histogram aggregation. Options include BASE2_EXPONENTIAL_BUCKET_HISTOGRAM and EXPLICIT_BUCKET_HISTOGRAM.EXPLICIT_BUCKET_HISTOGRAM
otel.experimental.exporter.otlp.retry.enabledIf true, enable experimental retry support.false
OTLP exporter retry

OTLP requires that transient errors be handled with a retry strategy. When retry is enabled, retryable gRPC status codes are retried using an exponential backoff with jitter algorithm as described in the gRPC Retry Design.

The policy has the following configuration, which is can only be customized via programmatic configuration (see customizing the OpenTelemetry SDK):

OptionDescriptionDefault
maxAttemptsThe maximum number of attempts, including the original request.5
initialBackoffThe initial backoff duration.1s
maxBackoffThe maximum backoff duration.5s
backoffMultiplierThe backoff multiplier.1.5

Logging exporter

The logging exporter prints the name of the span along with its attributes to stdout. It’s mainly used for testing and debugging.

This configuration option applies when using the opentelemetry-exporter-logging artifact. For full artifact ID and version information, reference the SDK exporter list.

Environment variableDescription
otel.{signal}.exporter=consoleSelect the logging exporter for {signal}.

The logging exporter is also set when otel.{signal}.exporter, is set to logging. logging is a deprecated alias for console, the preferred value as defined in the specification.

Logging OTLP JSON exporter

The logging-otlp exporter writes the telemetry data to the JUL logger in OTLP JSON form. It’s a more verbose output mainly used for testing and debugging.

This configuration option applies when using the opentelemetry-exporter-logging-otlp artifact. For full artifact ID and version information, reference the SDK exporter list.

Environment variableDescription
otel.{signal}.exporter=logging-otlpSelect the logging OTLP JSON exporter for {signal}.

Tracer provider

The following configuration options are specific to SdkTracerProvider. See general configuration for general configuration.

Span exporters

The following exporters are only available for the trace signal. See exporters for general exporter configuration.

Jaeger exporter

Jaeger now has native support for OTLP, and users should export to Jaeger using OTLP instead.

Zipkin exporter

The Zipkin exporter sends JSON in Zipkin format to a specified HTTP URL.

These configuration options apply when using the opentelemetry-exporter-zipkin artifact. For full artifact ID and version information, reference the SDK exporter list.

System propertyDescription
otel.traces.exporter=zipkinSelect the Zipkin exporter
otel.exporter.zipkin.endpointThe Zipkin endpoint to connect to. Default is http://localhost:9411/api/v2/spans. Currently only HTTP is supported.

Batch span processor

System propertyDescriptionDefault
otel.bsp.schedule.delayThe interval, in milliseconds, between two consecutive exports.5000
otel.bsp.max.queue.sizeThe maximum queue size.2048
otel.bsp.max.export.batch.sizeThe maximum batch size.512
otel.bsp.export.timeoutThe maximum allowed time, in milliseconds, to export data.30000

Sampler

The sampler configures whether spans will be recorded for any call to SpanBuilder.startSpan.

System propertyDescriptionDefault
otel.traces.samplerThe sampler to use for tracing.parentbased_always_on
otel.traces.sampler.argAn argument to the configured tracer if supported, for example a ratio.

Supported values for otel.traces.sampler are:

ValueDescription
always_onAlwaysOnSampler
always_offAlwaysOffSampler
traceidratioTraceIdRatioBased. otel.traces.sampler.arg sets the ratio.
parentbased_always_onParentBased(root=AlwaysOnSampler)
parentbased_always_offParentBased(root=AlwaysOffSampler)
parentbased_traceidratioParentBased(root=TraceIdRatioBased). otel.traces.sampler.arg sets the ratio.

Span limits

See attribute limits for general attribute limit configuration.

These properties can be used to control the maximum size of spans by placing limits on attributes, events, and links.

System propertyDescriptionDefault
otel.span.attribute.value.length.limitThe maximum length of span attribute values. Takes precedence over otel.attribute.value.length.limit.No limit
otel.span.attribute.count.limitThe maximum number of attributes per span. Takes precedence over otel.attribute.count.limit.128
otel.span.event.count.limitThe maximum number of events per span.128
otel.span.link.count.limitThe maximum number of links per span.128

Meter provider

The following configuration options are specific to SdkMeterProvider. See general configuration for general configuration.

Exemplars

System propertyDescriptionDefault
otel.metrics.exemplar.filterThe filter for exemplar sampling. Can be ALWAYS_OFF, ALWAYS_ON or TRACE_BASED.TRACE_BASED

Periodic Metric Reader

System propertyDescriptionDefault
otel.metric.export.intervalThe interval, in milliseconds, between the start of two export attempts.60000

Metric exporters

The following exporters are only available for the metric signal. See exporters for general exporter configuration.

Prometheus exporter

The Prometheus exporter.

The following configuration options apply when using the opentelemetry-exporter-prometheus artifact.

System propertyDescriptionDefault
otel.metrics.exporter=prometheusSelect the Prometheus exporter
otel.exporter.prometheus.portThe local port used to bind the prometheus metric server. Default is 9464.9464
otel.exporter.prometheus.hostThe local address used to bind the prometheus metric server. Default is 0.0.0.0.0.0.0.0

Note that this is a pull exporter - it opens up a server on the local process listening on the specified host and port, which a Prometheus server scrapes from.

Cardinality Limits

System propertyDescriptionDefault
otel.experimental.metrics.cardinality.limitIf set, configure experimental cardinality limit. The value dictates the maximum number of distinct points per metric.2000

Logger provider

The following configuration options are specific to SdkLoggerProvider. See general configuration for general configuration.

Batch log record processor

System propertyDescriptionDefault
otel.blrp.schedule.delayThe interval, in milliseconds, between two consecutive exports.1000
otel.blrp.max.queue.sizeThe maximum queue size.2048
otel.blrp.max.export.batch.sizeThe maximum batch size.512
otel.blrp.export.timeoutThe maximum allowed time, in milliseconds, to export data.30000

Customizing the OpenTelemetry SDK

Autoconfiguration exposes SPI hooks for customizing behavior programmatically as needed. It’s recommended to use the above configuration properties where possible, only implementing the SPI to add functionality not found in the SDK by default.

File Configuration

Status: Experimental

File configuration allows for configuration via a YAML as described in opentelemetry-configuration and file configuration.

To use, include io.opentelemetry:opentelemetry-sdk-extension:incubator:<version> and specify the path to the config file as described in the table below.

System propertyPurposeDefault
otel.experimental.config.fileThe path to the SDK configuration file.Unset

  1. Exporters which adhere to otel.java.experimental.exporter.memory_mode=reusable_data are OtlpGrpc{Signal}Exporter, OtlpHttp{Signal}Exporter, and PrometheusHttpServer↩︎

  2. OpenTelemetry Java agent 2.x uses http/protobuf by default. ↩︎ ↩︎