The SDK is the built-in reference implementation of the API, processing and exporting telemetry produced by instrumentation API calls. Configuring the SDK to process and export appropriately is an essential step to integrating OpenTelemetry into an application.

All SDK components have programmatic configuration APIs. This is the most flexible, expressive way to configure the SDK. However, changing configuration requires adjusting code and recompiling the application, and there is no language interoperability since the API is written in java.

The zero-code SDK autoconfigure module configures SDK components through system properties or environment variables, with various extension points for instances where the properties are insufficient.

{{% alert %}} We recommend using the zero-code SDK autoconfigure module since it reduces boilerplate code, allows reconfiguration without rewriting code or recompiling the application, and has language interoperability. {{% /alert %}}

{{% alert %}} The Java agent and Spring starter automatically configure the SDK using the zero-code SDK autoconfigure module, and install instrumentation with it. All autoconfigure content is applicable to Java agent and Spring starter users. {{% /alert %}}

The programmatic configuration interface is the set of APIs for constructing SDK components. All SDK components have a programmatic configuration API, and all other configuration mechanisms are built on top of this API. For example, the autoconfigure environment variable and system property configuration interface interprets well-known environment variables and system properties into a series of calls to the programmatic configuration API.

While other configuration mechanisms offer more convenience, none offer the flexibility of writing code expressing the precise configuration required. When a particular capability isn't supported by a higher order configuration mechanism, you might have no choice but to use programmatic configuration.

The SDK components sections demonstrate simple programmatic configuration API for key user-facing areas of the SDK. Consult the code for complete API reference.

The autoconfigure module (artifact io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:{{% param vers.otel %}}) is a configuration interface built on top of the programmatic configuration interface, which configures SDK components with zero code. There are two distinct autoconfigure workflows:

• Environment variables and system properties interprets environment variables and system properties to create SDK components, including various customization points for overlaying programmatic configuration.
• Declarative configuration (currently under development) interprets a configuration model to create SDK components, which is typically encoded in a YAML configuration file.

Automatically configure SDK components using with autoconfigure as follows:

package otel;

import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

public class AutoConfiguredSdk {
  public static OpenTelemetrySdk autoconfiguredSdk() {
    return AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
  }
}

{{% alert %}} The Java agent and Spring starter automatically configure the SDK using the zero-code SDK autoconfigure module, and install instrumentation with it. All autoconfigure content is applicable to Java agent and Spring starter users. {{% /alert %}}

{{% alert color="info" %}} The autoconfigure module registers Java shutdown hooks to shut down the SDK when appropriate. Because OpenTelemetry Java uses java.util.logging for internal logging, some logging might be suppressed during shutdown hooks. This is a bug in the JDK itself, and not something under the control of OpenTelemetry Java. If you require logging during shutdown hooks, consider using System.out rather than a logging framework which might shut itself down in a shutdown hook, thus suppressing your log messages. For more details, see this JDK bug. {{% /alert %}}

The autoconfigure module supports properties listed in the environment variable configuration specification, with occasional experimental and Java-specific additions.

The following properties are listed as system properties, but can also be set using environment variables. Apply the following steps to convert a system property to an environment variable:

• Convert the name to uppercase.
• Replace all . and - characters with _.

For example, the otel.sdk.enabled system property is equivalent to the OTEL_SDK_ENABLED environment variable.

If a property is defined as both a system property and environment variable, the system property takes priority.

Properties for disabling the SDK:

[1]: If disabled, AutoConfiguredOpenTelemetrySdk#getOpenTelemetrySdk() returns a minimally configured instance (for example, OpenTelemetrySdk.builder().build()).

Properties for attribute limits (see span limits, log limits):

Properties for context propagation:

[1]: Known propagators and artifacts (see text map propagator for artifact coordinates):

• tracecontext configures W3CTraceContextPropagator.
• baggage configures W3CBaggagePropagator.
• b3, b3multi configures B3Propagator.
• jaeger configures JaegerPropagator.
• ottrace configures OtTracePropagator.
• xray configures AwsXrayPropagator.
• xray-lambda configures AwsXrayLambdaPropagator.

Properties for configuring resource:

[1]: For example, to disable the OS resource provider, set -Dotel.java.disabled.resource.providers=io.opentelemetry.instrumentation.resources.OsResourceProvider.

NOTE: The otel.service.name and otel.resource.attributes system properties / environment variables are interpreted in the io.opentelemetry.sdk.autoconfigure.EnvironmentResourceProvider resource provider. If opting in to specify resource providers via otel.java.enabled.resource-providers, you'll likely want to include it to avoid surprises. See ResourceProvider for resource provider artifact coordinates.

Properties for batch span processor(s) paired with exporters specified via otel.traces.exporter:

Properties for sampler:

[1]: Known samplers and artifacts (see sampler for artifact coordinates):

• always_on configures AlwaysOnSampler.
• always_off configures AlwaysOffSampler.
• traceidratio configures TraceIdRatioBased. otel.traces.sampler.arg sets the ratio.
• parentbased_always_on configures ParentBased(root=AlwaysOnSampler).
• parentbased_always_off configures ParentBased(root=AlwaysOffSampler).
• parentbased_traceidratio configures ParentBased(root=TraceIdRatioBased). otel.traces.sampler.arg sets the ratio.
• jaeger_remote configures JaegerRemoteSampler. otel.traces.sampler.arg is a comma-separated list of args as described in the specification.

Properties for span limits:

Properties for periodic metric reader:

Properties for exemplars:

Properties for cardinality limits:

Properties for log record processor(s) pared with exporters via otel.logs.exporter:

Properties for setting exporters:

[1]: Known exporters and artifacts (see span exporter, metric exporter, log exporter for exporter artifact coordinates):

• otlp configures OtlpHttp{Signal}Exporter / OtlpGrpc{Signal}Exporter.
• zipkin configures ZipkinSpanExporter.
• console configures LoggingSpanExporter, LoggingMetricExporter, SystemOutLogRecordExporter.
• logging-otlp configures OtlpJsonLogging{Signal}Exporter.
• experimental-otlp/stdout configures OtlpStdout{Signal}Exporter (this option is experimental and subject to change or removal).

[2]: Exporters which adhere to otel.java.exporter.memory_mode=reusable_data are OtlpGrpc{Signal}Exporter, OtlpHttp{Signal}Exporter, OtlpStdout{Signal}Exporter, and PrometheusHttpServer.

Properties for otlp span, metric, and log exporters:

NOTE: The text placeholder {signal} refers to the supported OpenTelemetry Signal. Valid values include traces, metrics, and logs. Signal specific configurations take priority over the generic versions. For example, if you set both otel.exporter.otlp.endpoint and otel.exporter.otlp.traces.endpoint, the latter will take precedence.

[1]: OpenTelemetry Java agent 2.x and the OpenTelemetry Spring Boot starter use http/protobuf by default.

[2]: OTLP requires transient errors to be handled with a retry strategy. When retry is enabled, retryable gRPC status codes are retried using an exponential backoff with jitter algorithm. The specific options of RetryPolicy can only be customized via programmatic customization.

Properties for zipkin span exporter:

Properties for prometheus metric exporter.

Programmatic customization provides hooks to supplement the supported properties with programmatic configuration.

If using the Spring starter, see also spring starter programmatic configuration.

package otel;

import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
import java.util.Collections;

public class CustomizedAutoConfiguredSdk {
  public static OpenTelemetrySdk autoconfiguredSdk() {
    return AutoConfiguredOpenTelemetrySdk.builder()
        // Optionally customize TextMapPropagator.
        .addPropagatorCustomizer((textMapPropagator, configProperties) -> textMapPropagator)
        // Optionally customize Resource.
        .addResourceCustomizer((resource, configProperties) -> resource)
        // Optionally customize Sampler.
        .addSamplerCustomizer((sampler, configProperties) -> sampler)
        // Optionally customize SpanExporter.
        .addSpanExporterCustomizer((spanExporter, configProperties) -> spanExporter)
        // Optionally customize SpanProcessor.
        .addSpanProcessorCustomizer((spanProcessor, configProperties) -> spanProcessor)
        // Optionally supply additional properties.
        .addPropertiesSupplier(Collections::emptyMap)
        // Optionally customize ConfigProperties.
        .addPropertiesCustomizer(configProperties -> Collections.emptyMap())
        // Optionally customize SdkTracerProviderBuilder.
        .addTracerProviderCustomizer((builder, configProperties) -> builder)
        // Optionally customize SdkMeterProviderBuilder.
        .addMeterProviderCustomizer((builder, configProperties) -> builder)
        // Optionally customize MetricExporter.
        .addMetricExporterCustomizer((metricExporter, configProperties) -> metricExporter)
        // Optionally customize MetricReader.
        .addMetricReaderCustomizer((metricReader, configProperties) -> metricReader)
        // Optionally customize SdkLoggerProviderBuilder.
        .addLoggerProviderCustomizer((builder, configProperties) -> builder)
        // Optionally customize LogRecordExporter.
        .addLogRecordExporterCustomizer((logRecordExporter, configProperties) -> logRecordExporter)
        // Optionally customize LogRecordProcessor.
        .addLogRecordProcessorCustomizer((processor, configProperties) -> processor)
        .build()
        .getOpenTelemetrySdk();
  }
}

SPIs (artifact io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi:{{% param vers.otel %}}) extend SDK autoconfiguration beyond the components built-in to the SDK.

The following sections describe the available SPIs. Each SPI section includes:

• A brief description, including link to Javadoc type reference.
• A table of available built-in and opentelemetry-java-contrib implementations.
• A simple demonstration of a custom implementation.

ResourceProviders contribute to the autoconfigured resource.

ResourceProviders built-in to the SDK and maintained by the community in opentelemetry-java-contrib:

Implement the ResourceProvider interface to participate in resource autoconfiguration. For example:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.ResourceProvider;
import io.opentelemetry.sdk.resources.Resource;

public class CustomResourceProvider implements ResourceProvider {

  @Override
  public Resource createResource(ConfigProperties config) {
    // Callback invoked to contribute to the resource.
    return Resource.builder().put("my.custom.resource.attribute", "abc123").build();
  }

  @Override
  public int order() {
    // Optionally influence the order of invocation.
    return 0;
  }
}

Implement the AutoConfigurationCustomizerProvider interface to customize a variety of autoconfigured SDK components. For example:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizer;
import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider;
import java.util.Collections;

public class CustomizerProvider implements AutoConfigurationCustomizerProvider {

  @Override
  public void customize(AutoConfigurationCustomizer customizer) {
    // Optionally customize TextMapPropagator.
    customizer.addPropagatorCustomizer((textMapPropagator, configProperties) -> textMapPropagator);
    // Optionally customize Resource.
    customizer.addResourceCustomizer((resource, configProperties) -> resource);
    // Optionally customize Sampler.
    customizer.addSamplerCustomizer((sampler, configProperties) -> sampler);
    // Optionally customize SpanExporter.
    customizer.addSpanExporterCustomizer((spanExporter, configProperties) -> spanExporter);
    // Optionally customize SpanProcessor.
    customizer.addSpanProcessorCustomizer((spanProcessor, configProperties) -> spanProcessor);
    // Optionally supply additional properties.
    customizer.addPropertiesSupplier(Collections::emptyMap);
    // Optionally customize ConfigProperties.
    customizer.addPropertiesCustomizer(configProperties -> Collections.emptyMap());
    // Optionally customize SdkTracerProviderBuilder.
    customizer.addTracerProviderCustomizer((builder, configProperties) -> builder);
    // Optionally customize SdkMeterProviderBuilder.
    customizer.addMeterProviderCustomizer((builder, configProperties) -> builder);
    // Optionally customize MetricExporter.
    customizer.addMetricExporterCustomizer((metricExporter, configProperties) -> metricExporter);
    // Optionally customize MetricReader.
    customizer.addMetricReaderCustomizer((metricReader, configProperties) -> metricReader);
    // Optionally customize SdkLoggerProviderBuilder.
    customizer.addLoggerProviderCustomizer((builder, configProperties) -> builder);
    // Optionally customize LogRecordExporter.
    customizer.addLogRecordExporterCustomizer((exporter, configProperties) -> exporter);
    // Optionally customize LogRecordProcessor.
    customizer.addLogRecordProcessorCustomizer((processor, configProperties) -> processor);
  }

  @Override
  public int order() {
    // Optionally influence the order of invocation.
    return 0;
  }
}

Implement the ConfigurableSpanExporterProvider interface to allow a custom span exporter to participate in autoconfiguration. For example:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSpanExporterProvider;
import io.opentelemetry.sdk.trace.export.SpanExporter;

public class CustomSpanExporterProvider implements ConfigurableSpanExporterProvider {

  @Override
  public SpanExporter createExporter(ConfigProperties config) {
    // Callback invoked when OTEL_TRACES_EXPORTER includes the value from getName().
    return new CustomSpanExporter();
  }

  @Override
  public String getName() {
    return "custom-exporter";
  }
}

Implement the ConfigurableMetricExporterProvider interface to allow a custom metric exporter to participate in autoconfiguration. For example:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.metrics.ConfigurableMetricExporterProvider;
import io.opentelemetry.sdk.metrics.export.MetricExporter;

public class CustomMetricExporterProvider implements ConfigurableMetricExporterProvider {

  @Override
  public MetricExporter createExporter(ConfigProperties config) {
    // Callback invoked when OTEL_METRICS_EXPORTER includes the value from getName().
    return new CustomMetricExporter();
  }

  @Override
  public String getName() {
    return "custom-exporter";
  }
}

Implement the ConfigurableLogRecordExporterProvider interface to allow a custom log record exporter to participate in autoconfiguration. For example:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.logs.ConfigurableLogRecordExporterProvider;
import io.opentelemetry.sdk.logs.export.LogRecordExporter;

public class CustomLogRecordExporterProvider implements ConfigurableLogRecordExporterProvider {

  @Override
  public LogRecordExporter createExporter(ConfigProperties config) {
    // Callback invoked when OTEL_LOGS_EXPORTER includes the value from getName().
    return new CustomLogRecordExporter();
  }

  @Override
  public String getName() {
    return "custom-exporter";
  }
}

Implement the ConfigurableSamplerProvider interface to allow a custom sampler to participate in autoconfiguration. For example:

package otel;

import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSamplerProvider;
import io.opentelemetry.sdk.trace.samplers.Sampler;

public class CustomSamplerProvider implements ConfigurableSamplerProvider {

  @Override
  public Sampler createSampler(ConfigProperties config) {
    // Callback invoked when OTEL_TRACES_SAMPLER is set to the value from getName().
    return new CustomSampler();
  }

  @Override
  public String getName() {
    return "custom-sampler";
  }
}

Implement the ConfigurablePropagatorProvider interface to allow a custom propagator to participate in autoconfiguration. For example:

package otel;

import io.opentelemetry.context.propagation.TextMapPropagator;
import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.ConfigurablePropagatorProvider;

public class CustomTextMapPropagatorProvider implements ConfigurablePropagatorProvider {
  @Override
  public TextMapPropagator getPropagator(ConfigProperties config) {
    // Callback invoked when OTEL_PROPAGATORS includes the value from getName().
    return new CustomTextMapPropagator();
  }

  @Override
  public String getName() {
    return "custom-propagator";
  }
}

Declarative configuration is currently under development. It allows for YAML file-based configuration as described in opentelemetry-configuration and declarative configuration.

To use, include io.opentelemetry:opentelemetry-sdk-extension-incubator:{{% param vers.otel %}}-alpha and specify the path to the config file as described in the table below.

{{% alert title="Note" color="warning" %}} When a config file is specified, environment variables and system properties are ignored, programmatic customization and SPIs are skipped. The contents of the file alone dictate SDK configuration. {{% /alert %}}

For additional details, consult the following resources:

• Usage documentation
• Example with Java agent
• Example without Java agent