Configure the SDK

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.

Programmatic configuration

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.

Zero-code SDK autoconfigure

The autoconfigure module (artifact io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.45.0) 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();
  }
}

Environment variables and system properties

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: general

Properties for disabling the SDK:

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

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

Properties for configuring resource:

System propertyDescriptionDefault
otel.service.nameSpecify logical service name. Takes precedence over service.name defined with otel.resource.attributes.unknown_service:java
otel.resource.attributesSpecify resource attributes in the following format: key1=val1,key2=val2,key3=val3.
otel.resource.disabled-keysSpecify resource attribute keys to filter.
otel.java.enabled.resource.providersComma-separated list of ResourceProvider fully qualified class names to enable. [1] If unset, all resource providers are enabled.
otel.java.disabled.resource.providersComma-separated list of ResourceProvider fully qualified class names to disable. [1]

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

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

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

Properties for context propagation:

System propertyDescriptionDefault
otel.propagatorsComma-separated list of propagators. Known values include tracecontext, baggage, b3, b3multi, jaeger, ottrace, xray, xray-lambda. [1]tracecontext,baggage (W3C)

[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: traces

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

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

Properties for sampler:

System propertyDescriptionDefault
otel.traces.samplerThe sampler to use. Known values include always_on, always_off, traceidratio, parentbased_always_on, parentbased_always_off, parentbased_traceidratio, jaeger_remote. [1]parentbased_always_on
otel.traces.sampler.argAn argument to the configured tracer if supported, for example a ratio.

[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:

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

Properties: metrics

Properties for periodic metric reader:

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

Properties for exemplars:

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

Properties for cardinality limits:

System propertyDescriptionDefault
otel.experimental.metrics.cardinality.limitIf set, configure cardinality limit. The value dictates the maximum number of distinct points per metric. This option is experimental and subject to change or removal.2000

Properties: logs

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

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

Properties: exporters

Properties for setting exporters:

System propertyPurposeDefault
otel.traces.exporterComma-separated list of span exporters. Known values include otlp, zipkin, console, logging-otlp, none. [1]otlp
otel.metrics.exporterComma-separated list of metric exporters. Known values include otlp, prometheus, none. [1]otlp
otel.logs.exporterComma-separated list of log record exporters. Known values include otlp, console, logging-otlp, none. [1]otlp
otel.java.exporter.memory_modeIf reusable_data, enable reusable memory mode (on exporters which support it) to reduce allocations. Known values include reusable_data, immutable_data. [2]reusable_data

[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:

System propertyDescriptionDefault
otel.{signal}.exporter=otlpSelect the OpenTelemetry exporter for {signal}.
otel.exporter.otlp.protocolThe transport protocol to use on OTLP trace, metric, and log requests. Options include grpc and http/protobuf.grpc [1]
otel.exporter.otlp.{signal}.protocolThe transport protocol to use on OTLP {signal} requests. Options include grpc and http/protobuf.grpc [1]
otel.exporter.otlp.endpointThe endpoint to send all OTLP traces, metrics, and logs to. Often the address of an OpenTelemetry Collector. 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 when protocol is http/protobuf.
otel.exporter.otlp.{signal}.endpointThe endpoint to send OTLP {signal} to. Often the address of an OpenTelemetry Collector. 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 must 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.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.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.java.exporter.otlp.retry.enabledIf true, retry on when transient errors occur. [2]true

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:

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

Properties for prometheus metric exporter.

System propertyDescriptionDefault
otel.metrics.exporter=prometheusSelect the Prometheus exporter
otel.exporter.prometheus.portThe local port used to bind the prometheus metric server.9464
otel.exporter.prometheus.hostThe local address used to bind the prometheus metric server.0.0.0.0

Programmatic customization

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();
  }
}

SPI (Service provider interface)

SPIs (artifact io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi:1.45.0) 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.
ResourceProvider

ResourceProviders contribute to the autoconfigured resource.

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

ClassArtifactDescription
io.opentelemetry.instrumentation.resources.ContainerResourceProviderio.opentelemetry.instrumentation:opentelemetry-resources:2.10.0-alphaProvides container resource attributes.
io.opentelemetry.instrumentation.resources.HostResourceProviderio.opentelemetry.instrumentation:opentelemetry-resources:2.10.0-alphaProvides host resource attributes.
io.opentelemetry.instrumentation.resources.HostIdResourceProviderio.opentelemetry.instrumentation:opentelemetry-resources:2.10.0-alphaProvides host ID resource attribute.
io.opentelemetry.instrumentation.resources.ManifestResourceProviderio.opentelemetry.instrumentation:opentelemetry-resources:2.10.0-alphaProvides service resource attributes based on jar manifest.
io.opentelemetry.instrumentation.resources.OsResourceProviderio.opentelemetry.instrumentation:opentelemetry-resources:2.10.0-alphaProvides OS resource attributes.
io.opentelemetry.instrumentation.resources.ProcessResourceProviderio.opentelemetry.instrumentation:opentelemetry-resources:2.10.0-alphaProvides process resource attributes.
io.opentelemetry.instrumentation.resources.ProcessRuntimeProviderio.opentelemetry.instrumentation:opentelemetry-resources:2.10.0-alphaProvides process runtime resource attributes.
io.opentelemetry.contrib.gcp.resource.GCPResourceProviderio.opentelemetry.contrib:opentelemetry-gcp-resources:1.42.0-alphaProvides GCP runtime environment resource attributes.
io.opentelemetry.contrib.aws.resource.BeanstalkResourceProviderio.opentelemetry.contrib:opentelemetry-aws-resources:1.42.0-alphaProvides AWS beanstalk runtime environment resource attributes.
io.opentelemetry.contrib.aws.resource.Ec2ResourceProviderio.opentelemetry.contrib:opentelemetry-aws-resources:1.42.0-alphaProvides AWS ec2 runtime environment resource attributes.
io.opentelemetry.contrib.aws.resource.EcsResourceProviderio.opentelemetry.contrib:opentelemetry-aws-resources:1.42.0-alphaProvides AWS ecs runtime environment resource attributes.
io.opentelemetry.contrib.aws.resource.EksResourceProviderio.opentelemetry.contrib:opentelemetry-aws-resources:1.42.0-alphaProvides AWS eks runtime environment resource attributes.
io.opentelemetry.contrib.aws.resource.LambdaResourceProviderio.opentelemetry.contrib:opentelemetry-aws-resources:1.42.0-alphaProvides AWS lambda runtime environment resource attributes.

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;
  }
}
AutoConfigurationCustomizerProvider

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;
  }
}
ConfigurableSpanExporterProvider

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";
  }
}
ConfigurableMetricExporterProvider

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";
  }
}
ConfigurableLogRecordExporterProvider

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";
  }
}
ConfigurableSamplerProvider

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";
  }
}
ConfigurablePropagatorProvider

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

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:1.45.0-alpha 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

For additional details, consult the following resources:


Last modified December 20, 2024: Update configuration.md (#5832) (bf5ab3f0)