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.
The variables
Section titled “The variables”| Env var | Field | Default |
|---|---|---|
OTEL_SERVICE_NAME, then service.name in OTEL_RESOURCE_ATTRIBUTES | service_name | the 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_ATTRIBUTES | service_version | the binary’s package version |
deployment.environment.name in OTEL_RESOURCE_ATTRIBUTES | deployment_environment | none |
service.instance.id in OTEL_RESOURCE_ATTRIBUTES | service_instance_id | fresh UUIDv7 per process |
RUST_LOG | log_filter | info, the baseline logger’s |
<PREFIX>_LOG_FORMAT | log_format | text under a declared development or test profile, json otherwise |
<PREFIX>_LOG_SOURCE_LOCATION | log_source_location | false |
OTEL_EXPORTER_OTLP_ENDPOINT, then per signal OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (_METRICS_, _LOGS_) | otlp_endpoint | none: console-only |
OTEL_TRACES_SAMPLER, with OTEL_TRACES_SAMPLER_ARG | trace_sample_ratio | 1.0, parent-based |
OTEL_METRIC_EXPORT_INTERVAL (milliseconds) | metric_interval | 60 s |
OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_CLIENT_KEY (and per signal) | tls | the 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_*orOTEL_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:512fails 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_DELAYorOTEL_BLRP_SCHEDULE_DELAYunder 1 ms, on which the SDK’s worker polls its channel without pause — a core for each processor, idle or not — and anOTEL_BSP_MAX_QUEUE_SIZEorOTEL_BLRP_MAX_QUEUE_SIZEabove 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 blankservice.nameinOTEL_RESOURCE_ATTRIBUTES, or a pinnedservice_nameof either. An emptyOTEL_SERVICE_NAMEis unset, as the specification reads an empty variable, and the binary names the service. OTEL_RESOURCE_ATTRIBUTESis read as the resource specification writes it,key=valuepairs separated by commas, each key and value percent-decoded: a comma or an equals sign in one is written%2Cor%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) takesgzip, the one compression the OTLP specification names, ornone;zstdand anything else fail.OTEL_EXPORTER_OTLP_PROTOCOL(or a signal’s own) may only sayhttp/protobuf, the one protocol this exporter speaks, rather than send protobuf to a port that expects gRPC.OTEL_TRACES_SAMPLERmay only name a sampler the SDK builds, andOTEL_TRACES_SAMPLER_ARGa ratio between 0 and 1 (Sampling).OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCEtakescumulative(default),deltaorlowmemory, in any case.OTEL_PROPAGATORSmay only nametracecontextandbaggage, its default. The framework propagates W3C Trace Context at every edge itself (Correlation), and W3C Baggage reaches the queue alone: a job carries thebaggageit 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, andnone, which cannot turn that correlation off, fail.OTEL_CONFIG_FILEfails: 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.
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \OTEL_TRACES_EXPORTER=none \ nestrs run start apiThe 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.
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 apiA 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:
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.
An encrypted export
Section titled “An encrypted export”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.
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.internal:4318 \OTEL_EXPORTER_OTLP_CERTIFICATE=/run/secrets/collector-ca.pem \ nestrs run start apiGoing further
Section titled “Going further”- OpenTelemetry — the one line of
mainthis configures. - Logs — the console’s format and level, beside the export.
- Traces — the sampler
OTEL_TRACES_SAMPLERpicks.