Skip to content

OpenTelemetry configuration

The OTEL_* variables the exporter reads over a pinned OpenTelemetryConfig, and the TLS, timeouts and headers an encrypted export runs on.

The exporter reads the variables the OpenTelemetry specification names — the ones the OpenTelemetry Operator injects and every other SDK reads — with no prefix: OTEL_* belongs to the ecosystem, as RUST_LOG does. They and the console’s three override what OpenTelemetryConfig pins, field by field; OpenTelemetry::init() starts from the defaults, and OpenTelemetry::init_with(cfg) from a pinned config.

Env varFieldDefault
OTEL_SERVICE_NAME, then service.name in OTEL_RESOURCE_ATTRIBUTESservice_namethe binary’s package name, or the specification’s unknown_service:<executable> in a binary #[nest_rs::main] did not start
service.version in OTEL_RESOURCE_ATTRIBUTESservice_versionthe binary’s package version
deployment.environment.name in OTEL_RESOURCE_ATTRIBUTESdeployment_environmentnone
service.instance.id in OTEL_RESOURCE_ATTRIBUTESservice_instance_idfresh UUIDv7 per process
RUST_LOGlog_filterinfo, the baseline logger’s
<PREFIX>_LOG_FORMATlog_formattext under a declared development or test profile, json otherwise
<PREFIX>_LOG_SOURCE_LOCATIONlog_source_locationfalse
OTEL_EXPORTER_OTLP_ENDPOINT, then per signal OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (_METRICS_, _LOGS_)otlp_endpointnone: console-only
OTEL_TRACES_SAMPLER, with OTEL_TRACES_SAMPLER_ARGtrace_sample_ratio1.0, parent-based
OTEL_METRIC_EXPORT_INTERVAL (milliseconds)metric_interval60 s
OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_CLIENT_KEY (and per signal)tlsthe system’s authorities, no client certificate

The batch processors’ OTEL_BSP_* and OTEL_BLRP_* the SDK reads as it always does; the span limits — OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT, OTEL_SPAN_EVENT_COUNT_LIMIT, OTEL_SPAN_LINK_COUNT_LIMIT, OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT and OTEL_LINK_ATTRIBUTE_COUNT_LIMIT, the three attribute counts falling back on OTEL_ATTRIBUTE_COUNT_LIMIT — are read here and handed to the tracer, where the SDK reads three of them and not the general one. What this crate cannot honour fails the boot, naming the variable and never its value:

  • A number the SDK would pass over and keep its default in its place — an OTEL_BSP_* or OTEL_BLRP_* setting, a span limit, a timeout or the metric period that is not a whole number its type holds — fails, as the reference SDK’s autoconfiguration fails it. The batch processors’ settings are matched as the SDK matches them, digits alone: 512 fails too.
  • A batch processor’s queue or batch size of zero fails, as the specification’s sizes are positive: a queue of none takes no span or record. So does a batch written above its queue (OTEL_BSP_MAX_QUEUE_SIZE, 2048 when unset), which the SDK would lower to the queue in silence.
  • A batch processor’s number the SDK would turn into a spin or into an allocation no process holds fails, as the metric period outside a second to an hour does: an OTEL_BSP_SCHEDULE_DELAY or OTEL_BLRP_SCHEDULE_DELAY under 1 ms, on which the SDK’s worker polls its channel without pause — a core for each processor, idle or not — and an OTEL_BSP_MAX_QUEUE_SIZE or OTEL_BLRP_MAX_QUEUE_SIZE above 1,048,576. The SDK allocates the whole queue when its processor starts, and its worker a buffer as large as the batch, which may reach the queue: under opentelemetry_sdk 0.33 a span takes 368 bytes of the queue and 352 of the buffer, so the ceiling holds up to 720 MiB of spans up front, and a log record 16 and 8 bytes, 24 MiB, the record itself allocated as it is queued. The refusal says what the linked SDK takes.
  • A service name that names nothing fails: a blank OTEL_SERVICE_NAME, which the SDK would export under, an empty or blank service.name in OTEL_RESOURCE_ATTRIBUTES, or a pinned service_name of either. An empty OTEL_SERVICE_NAME is unset, as the specification reads an empty variable, and the binary names the service.
  • OTEL_RESOURCE_ATTRIBUTES is read as the resource specification writes it, key=value pairs separated by commas, each key and value percent-decoded: a comma or an equals sign in one is written %2C or %3D. A member with no = or an empty key, which the SDK would drop or export under no name, and an escape that does not decode, fail.
  • OTEL_EXPORTER_OTLP_COMPRESSION (or a signal’s own) takes gzip, the one compression the OTLP specification names, or none; zstd and anything else fail.
  • OTEL_EXPORTER_OTLP_PROTOCOL (or a signal’s own) may only say http/protobuf, the one protocol this exporter speaks, rather than send protobuf to a port that expects gRPC.
  • OTEL_TRACES_SAMPLER may only name a sampler the SDK builds, and OTEL_TRACES_SAMPLER_ARG a ratio between 0 and 1 (Sampling).
  • OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE takes cumulative (default), delta or lowmemory, in any case.
  • OTEL_PROPAGATORS may only name tracecontext and baggage, its default. The framework propagates W3C Trace Context at every edge itself (Correlation), and W3C Baggage reaches the queue alone: a job carries the baggage it came with onto every push it makes, and no HTTP, WebSocket, GraphQL or MCP request reads or answers one. Another format (b3, jaeger), a list leaving one of the two out, and none, which cannot turn that correlation off, fail.
  • OTEL_CONFIG_FILE fails: the Rust SDK has no file configuration, so nothing in the file would apply.

A specification variable no crate this build links reads, nor offers a setting for, is said once at warn on nest_rs::opentelemetry — an OpenTelemetry variable is passed over, its variable and the reason — rather than refused, since a platform sets it for every service’s SDK: OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT, OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT and OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT (values are exported whole), OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT (and OTEL_ATTRIBUTE_COUNT_LIMIT while the logs export: no log record’s attributes are limited), OTEL_METRICS_EXEMPLAR_FILTER, OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION, the SDK’s own OTEL_BSP_MAX_CONCURRENT_EXPORTS, OTEL_EXPORTER_OTLP_INSECURE and its per-signal spellings, which apply to gRPC alone since over OTLP/HTTP the endpoint’s scheme decides, and OTEL_LOG_LEVEL, whose subject — the SDK’s own lines — follows the console’s filter here, as every library’s does (RUST_LOG=info,opentelemetry_sdk=debug). A value that names what the build does says nothing: OTEL_METRICS_EXEMPLAR_FILTER=always_off, explicit_bucket_histogram, one concurrent export, OTEL_EXPORTER_OTLP_INSECURE=false.

The console’s three variables are read by the kernel’s one parser, as the baseline logger reads them: a value that does not parse fails init with OpenTelemetryError::LogSettings, naming the variable and never its value, and a log_filter pinned in code is checked the same way at init_with, naming OpenTelemetryConfig::log_filter.

Each signal exports only when an endpoint is set for it. OTEL_EXPORTER_OTLP_ENDPOINT is the base every signal appends its path to (/v1/traces, /v1/metrics, /v1/logs); a signal’s own variable is used as given, query and all. A query on the base fails the boot: the specification sends each signal to a path relative to the base, which leaves it no place — set each signal’s own endpoint, or move the parameter to a header. Without any endpoint, the subscriber stays console-only; the W3C propagator is still installed so an inbound traceparent is continued behind a trusted proxy and the response carries traceresponse.

The specification’s selectors switch a signal off whatever endpoint names it. OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER and OTEL_LOGS_EXPORTER take otlp, the default, or none, in any case, or a comma-separated list of otlp; OTEL_SDK_DISABLED=true turns all three off. Any other exporter — console, zipkin, prometheus, a misspelling — fails the boot naming the variable, and so do none beside otlp and otlp named for a signal no endpoint reaches: this crate builds the OTLP exporter alone, and a deployment that believes a signal ships where nothing ships is what the boot refuses. An OTEL_SDK_DISABLED that is neither true nor false leaves the SDK on, as the specification orders, and is said at warn.

Terminal window
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_TRACES_EXPORTER=none \
nestrs run start api

The boot line, OpenTelemetry initialised on nest_rs::opentelemetry, says where each signal goes: its traces, metrics and logs fields hold the endpoint, or why nothing is exported — off (OTEL_TRACES_EXPORTER=none), off (OTEL_SDK_DISABLED=true) or off (no endpoint) — each quoted on a text console, traces="off (no endpoint)", so a logfmt reader takes it whole. Its sampler is the sampler’s name as OTEL_TRACES_SAMPLER spells it, sampler_source what chose it, that variable or trace_sample_ratio, sample_ratio the share it samples on a sampler reading one, and log_format what the console writes.

Terminal window
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production \
OTEL_TRACES_SAMPLER=parentbased_traceidratio \
OTEL_TRACES_SAMPLER_ARG=0.1 \
RUST_LOG=info \
nestrs run start api

A pinned config holds the same settings in code, and the variables still override it, OTEL_* and the console’s alike — a deployment’s RUST_LOG=debug raises a filter pinned at warn:

main.rs
let _otel = OpenTelemetry::init_with(OpenTelemetryConfig {
trace_sample_ratio: 0.1,
..OpenTelemetryConfig::from_env()?
})?;

OpenTelemetryConfig is set one way — its fields, over OpenTelemetryConfig::default() or from_env() — and a pinned ratio outside [0, 1] or a metric period outside a second to an hour fails init_with naming the field.

Every variable here is read from the process environment, which #[nest_rs::main] fills with the .env cascade before main runs. Telemetry starts before any module, so a config pinned through init_with does not take its fields off the cascade as a module’s for_root pin does: a .env file’s value overrides it, as the deployment’s does.

The exporter uses HTTP/protobuf via reqwest (no tonic, no openssl) — the batch processors export from a dedicated non-Tokio thread so the blocking reqwest client is the right pick, the upstream-recommended pairing.

The endpoint’s scheme decides, as the OTLP specification lets it: an http:// endpoint exports in plaintext — a collector beside the app, as a sidecar or a node agent, is the common case — and an https:// one over TLS alone. Any other scheme, and a value that does not parse as a URL, fail the boot naming the variable that set it, never its value, which may carry a collector’s credential.

Off this machine’s loopback, a deployed profile says a plaintext export once per signal at warn on nest_rs::opentelemetry — a signal is exported over plain HTTP outside a dev profile, its signal and endpoint — and exports it all the same, since the deployment wrote it.

An https:// collector’s certificate is verified against the system’s authorities, or the ones in the file OTEL_EXPORTER_OTLP_CERTIFICATE names, which replace them; a collector requiring a client certificate gets the files OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE and OTEL_EXPORTER_OTLP_CLIENT_KEY name — both or neither. Each has its per-signal spelling (OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE, …), read first, and none is accepted beside an http:// endpoint, where it would go unused. All are read at the start, so a renewed file takes effect at the next one: rotate it with a rolling restart. The clients are this crate’s own: they follow no redirect, give up reaching the collector after 3 s, and cut each export where the SDK stops waiting for it — OTEL_EXPORTER_OTLP_TRACES_TIMEOUT (or _METRICS_, _LOGS_), then OTEL_EXPORTER_OTLP_TIMEOUT, in milliseconds, then 10 s. A metric export is also cut at OTEL_METRIC_EXPORT_TIMEOUT, the metric reader’s bound (30 s by default), whichever of the two comes first, and so is a span export at OTEL_BSP_EXPORT_TIMEOUT and a log export at OTEL_BLRP_EXPORT_TIMEOUT, each 30 s by default, which the batch processors the SDK builds read nowhere. A zero is no limit, as the specification reads a timeout’s zero, so the other of the two cuts the export; both at zero fail the boot, since every wait the framework owns is bounded. A value that is not a whole number of milliseconds fails the boot naming the variable, where the SDK would keep its default in silence; so does an OTEL_METRIC_EXPORT_INTERVAL that is not one.

A header the SDK sends — OTEL_EXPORTER_OTLP_HEADERS, or a signal’s own, key=value pairs separated by commas, a value percent-encoded where it needs to be — is read here as the SDK reads it and handed to each exporter. A signal’s own variable set empty reads as unset, as the specification orders, so the general headers reach that signal too; the SDK alone would send it none. A pair the SDK would drop in silence — no =, an empty key or value, a name no header may carry — fails the boot naming the variable. A credential goes there, never in the endpoint’s userinfo (https://user:pass@…), which no request carries: userinfo in any endpoint fails the boot naming what set it.

A header the SDK sends — OTEL_EXPORTER_OTLP_HEADERS, or a signal’s own, where a collector’s credential travels — fails the boot beside an http:// endpoint on another host, naming both variables: the credential would cross the network in clear, where RFC 6750 sends a bearer token over TLS alone, and no header’s name tells a credential from another. So does such an endpoint carrying a query (?api-key=…), which the request line carries, naming the variable that set it. To a collector on this host’s loopback — localhost, 127.0.0.1, [::1], a sidecar beside the app — both are sent, since they never leave the machine: the client dials it directly, past any proxy HTTP_PROXY, HTTPS_PROXY or ALL_PROXY names, which would reach its own host’s loopback instead. Every other collector is reached through the environment’s proxy, as any client is.

Terminal window
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.internal:4318 \
OTEL_EXPORTER_OTLP_CERTIFICATE=/run/secrets/collector-ca.pem \
nestrs run start api
  • OpenTelemetry — the one line of main this configures.
  • Logs — the console’s format and level, beside the export.
  • Traces — the sampler OTEL_TRACES_SAMPLER picks.