OpenTelemetry Protocol Exporter
This document specifies the configuration options available to the OpenTelemetry Protocol (OTLP) Exporter as well as the retry behavior.
The following configuration options MUST be available to configure the OTLP exporter. Each configuration option MUST be overridable by a signal specific option.
|Configuration Option||Description||Default||Env variable|
|Endpoint (OTLP/HTTP)||Target URL to which the exporter is going to send spans or metrics. The endpoint MUST be a valid URL with scheme (http or https) and host, MAY contain a port, SHOULD contain a path and MUST NOT contain other parts (such as query string or fragment). A scheme of https indicates a secure connection. When using
|Endpoint (OTLP/gRPC)||Target to which the exporter is going to send spans or metrics. The endpoint SHOULD accept any form allowed by the underlying gRPC client implementation. Additionally, the endpoint MUST accept a URL with a scheme of either
|Insecure||Whether to enable client transport security for the exporter’s gRPC connection. This option only applies to OTLP/gRPC - OTLP/HTTP always uses the scheme provided for the
|Certificate File||The trusted certificate to use when verifying a server’s TLS credentials. Should only be used for a secure connection.||n/a||
|Headers||Key-value pairs to be used as headers associated with gRPC or HTTP requests. See Specifying headers for more details.||n/a||
|Compression||Compression key for supported compression types. Supported compression:
||No value ||
|Timeout||Maximum time the OTLP exporter will wait for each batch export.||10s||
|Protocol||The transport protocol. Options MAY include
: SDKs SHOULD default endpoint variables to use
http scheme unless they have good reasons to choose
https scheme for the default (e.g., for backward compatibility reasons in a stable SDK release).
: If no compression value is explicitly specified, SIGs can default to the value they deem most useful among the supported options. This is especially important in the presence of technical constraints, e.g. directly sending telemetry data from mobile devices to backend servers.
Supported values for
noneif compression is disabled.
gzipis the only specified compression method for now.
Endpoint URLs for OTLP/HTTP
Based on the environment variables above, the OTLP/HTTP exporter MUST construct URLs for each signal as follow:
For the per-signal variables (
OTEL_EXPORTER_OTLP_<signal>_ENDPOINT), the URL MUST be used as-is without any modification. The only exception is that if an URL contains no path part, the root path
/MUST be used (see Example 2).
If signals are sent that have no per-signal configuration from the previous point,
OTEL_EXPORTER_OTLP_ENDPOINTis used as a base URL and the signals are sent to these paths relative to that:
Non-normatively, this could be implemented by ensuring that the base URL ends with a slash and then appending the relative URLs as strings.
An SDK MUST NOT modify the URL in ways other than specified above. That also means,
if the port is empty or not given, TCP port 80 is the default for the
and TCP port 443 is the default for the
https scheme, as per the usual rules
for these schemes (RFC 7230).
The following configuration sends all signals to the same collector:
Traces are sent to
http://collector:4318/v1/traces and metrics to
Traces and metrics are sent to different collectors and paths:
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://collector:4318 export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://collector.example.com/v1/metrics
This will send traces directly to the root path
/v1/traces is only automatically added when using the non-signal-specific
environment variable) and metrics
https://collector.example.com/v1/metrics, using the default https port (443).
The following configuration sends all signals except for metrics to the same collector:
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318/mycollector/ export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://collector.example.com/v1/metrics/
Traces are sent to
and metrics to
https://collector.example.com/v1/metrics/, using the default
https port (443).
Other signals, (if there were any) would be sent to their specific paths
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL environment variables specify the OTLP transport protocol. Supported values:
grpcfor protobuf-encoded data using gRPC wire format over HTTP/2 connection
http/protobuffor protobuf-encoded data over HTTP connection
http/jsonfor JSON-encoded data over HTTP connection
: SDKs SHOULD support both
http/protobuf transports and MUST
support at least one of them. If they support only one, it SHOULD be
http/protobuf. They also MAY support
If no configuration is provided the default transport SHOULD be
unless SDKs have good reasons to choose
grpc as the default (e.g. for backward
compatibility reasons when
grpc was already the default in a stable SDK
Specifying headers via environment variables
OTEL_EXPORTER_OTLP_METRICS_HEADERS environment variables will contain a list of key value pairs, and these are expected to be represented in a format matching to the W3C Correlation-Context, except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings.
Transient errors MUST be handled with a retry strategy. This retry strategy MUST implement an exponential back-off with jitter to avoid overwhelming the destination until the network is restored or the destination has recovered.
For OTLP/HTTP, the errors
408 (Request Timeout) and
5xx (Server Errors) are defined as transient, detailed information about erros can be found in the HTTP failures section. For the OTLP/gRPC, the full list of the gRPC retryable status codes can be found in the gRPC response section.