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:

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

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

$ export OTEL_SERVICE_NAME=auth-service

Common

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.

Telemetry resource detectors

TelemetryResourceDetector adds environment-aware attributes to the telemetry resource. For example, HostDetector will add host.arch and host.name attributes. By default, the following resource detectors are enabled: host, os, process, process_runtime.

To disable all detectors, set -Dotel.otel4s.resource.detectors.enabled=none. To disable some detectors, use -Dotel.otel4s.resource.detectors.disabled=host,os,process.

Metrics

Exporters

Options supported out of the box:

• otlp - requires otel4s-sdk-exporter dependency.
• prometheus - requires otel4s-sdk-exporter-prometheus dependency.
• console - prints metrics 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.metrics.{x}

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

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

Prometheus exporter

The exporter launches an HTTP server which responds to the HTTP requests with Prometheus metrics in the appropriate format.

Period metric reader

Period metric reader pushes metrics to the push-based exporters (e.g. OTLP) over a fixed interval.

Exemplar filter

The exemplar filter decides whether the measurement will be recorded as an exemplar.

The following options for otel.metrics.exemplar.filter are supported:

• always_on - all measurements eligible for being an exemplar.
• always_off - no measurements eligible for being an exemplar.
• trace_based - accepts measurements where there is a span in a context that is being sampled.

Tracing

Exporters

Options supported out of the box:

• otlp - requires otel4s-sdk-exporter dependency.
• console - 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 span 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.

Propagators

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

Options supported out of the box:

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

Batch span processor

Sampler

The sampler decides whether spans will be recorded.

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.

Span limits

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