Configuration

The OpenTelemetrySdk.autoConfigured(...) and SdkTraces.autoConfigured(...) rely on the environment variables and system properties to configure the SDK.

There are several ways to configure the options:

Add settings to the build.sbt:

javaOptions += "-Dotel.service.name=auth-service"
envVars ++= Map("OTEL_SERVICE_NAME" -> "auth-service")

Add directives to the *.scala file:

//> using javaOpt -Dotel.service.name=auth-service

$ export OTEL_SERVICE_NAME=auth-service

Common

System property	Environment variable	Description
otel.sdk.disabled	OTEL_SDK_DISABLED	If true returns a no-op SDK instance. Default is `false`.

Telemetry resource

It's highly recommended to specify the service.name for your application. For example, auth-service could be an application that handles authentication requests, and jobs-dispatcher could be an application that processes background jobs.

If not specified, SDK defaults the service name to unknown_service:scala.

System property	Environment variable	Description
otel.resource.attributes	OTEL_RESOURCE_ATTRIBUTES	Specify resource attributes in the following format: `key1=val1,key2=val2,key3=val3`.
otel.service.name	OTEL_SERVICE_NAME	Specify logical service name. Takes precedence over `service.name` defined with `otel.resource.attributes`.
otel.experimental.resource.disabled-keys	OTEL_EXPERIMENTAL_RESOURCE_DISABLED_KEYS	Specify resource attribute keys that are filtered.

Tracing

Exporters

System property	Environment variable	Description
otel.traces.exporter	OTEL_TRACES_EXPORTER	List of exporters to be export spans, separated by commas. `none` means no autoconfigured exporter. Default is `otlp`.

Options supported out of the box:

otlp - requires otel4s-sdk-exporter dependency.
logging - prints the name of the span along with its attributes to stdout. It's mainly used for testing and debugging.
none - means no autoconfigured exporter.

OTLP exporter

The exporter can be configured by two sets of settings:

global: otel.expoter.otlp.{x}
target-specific: otel.exporter.otlp.traces.{x}

Global properties can be used to configure tracer and metric exporters simultaneously. Global otel.exporter.otlp.endpoint must be a base URL. The configurer automatically adds path (i.e. v1/traces) to the URL.

Target-specific properties are prioritized. E.g. otel.exporter.otlp.traces.endpoint is prioritized over otel.exporter.otlp.endpoint.

System property	Environment variable	Description
otel.exporter.otlp.endpoint	OTEL_EXPORTER_OTLP_ENDPOINT	The OTLP traces, metrics, and logs endpoint to connect to. Must be a base URL with a scheme of either http or https based on the use of TLS. Default is `http://localhost:4318/`.
otel.exporter.otlp.headers	OTEL_EXPORTER_OTLP_HEADERS	Key-value pairs separated by commas to pass as request headers on OTLP trace, metric, and log requests.
otel.exporter.otlp.compression	OTEL_EXPORTER_OTLP_COMPRESSION	The compression type to use on OTLP trace, metric, and log requests. Options include gzip. By default, no compression will be used.
otel.exporter.otlp.timeout	OTEL_EXPORTER_OTLP_TIMEOUT	The maximum waiting time to send each OTLP trace, metric, and log batch. Default is `10 seconds`.
Target specific:
otel.exporter.otlp.traces.endpoint	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	The OTLP traces endpoint to connect to. Default is `http://localhost:4318/v1/traces`.
otel.exporter.otlp.traces.headers	OTEL_EXPORTER_OTLP_TRACES_HEADERS	Key-value pairs separated by commas to pass as request headers on OTLP trace requests.
otel.exporter.otlp.traces.compression	OTEL_EXPORTER_OTLP_TRACES_COMPRESSION	The compression type to use on OTLP trace requests. Options include gzip. By default, no compression will be used.
otel.exporter.otlp.traces.timeout	OTEL_EXPORTER_OTLP_TRACES_TIMEOUT	The maximum waiting time to send each OTLP trace batch. Default is `10 seconds`.

Propagators

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

System property	Environment variable	Description
otel.propagators	OTEL_PROPAGATORS	The propagators to use. Use a comma-separated list for multiple propagators. Default is `tracecontext,baggage` (W3C).

Options supported out of the box:

tracecontext - W3C Trace Context
baggage - W3C Baggage
b3 - B3 Single
b3multi - B3 Multi
jaeger - Jaeger

Batch span processor

System property	Environment variable	Description
otel.bsp.schedule.delay	OTEL_BSP_SCHEDULE_DELAY	The interval between two consecutive exports. Default is `5 seconds`.
otel.bsp.max.queue.size	OTEL_BSP_MAX_QUEUE_SIZE	The maximum queue size. Default is `2048`.
otel.bsp.max.export.batch.size	OTEL_BSP_MAX_EXPORT_BATCH_SIZE	The maximum batch size. Default is `512`.
otel.bsp.export.timeout	OTEL_BSP_EXPORT_TIMEOUT	The maximum allowed time to export data. Default is `30 seconds`.

Sampler

The sampler decides whether spans will be recorded.

System property	Environment variable	Description
otel.traces.sampler	OTEL_TRACES_SAMPLER	The sampler to use for tracing. Defaults to `parentbased_always_on`.
otel.traces.sampler.arg	OTEL_TRACES_SAMPLER_ARG	An argument to the configured tracer if supported, for example, a ratio.

The following options for otel.traces.sampler are supported out of the box:

always_on - always samples spans, regardless of the parent span's sampling decision.
always_off - never samples spans, regardless of the parent span's sampling decision.
traceidratio, where otel.traces.sampler.arg sets the ratio - samples probabilistically based on the configured rate.
parentbased_always_on - respects its parent span's sampling decision, but otherwise always samples.
parentbased_always_off - respects its parent span's sampling decision, but otherwise never samples.
parentbased_traceidratio, where otel.traces.sampler.arg sets the ratio - respects its parent span's sampling decision, but otherwise samples probabilistically based on the configured rate.