Status: Stable
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.
-
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
OTEL_EXPORTER_OTLP_ENDPOINT
, exporters MUST construct per-signal URLs as described below. The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications). See the OTLP Specification for more details.- Default:
http://localhost:4318
[1] - Env vars:
OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
- Default:
-
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
http
orhttps
. A scheme ofhttps
indicates a secure connection and takes precedence over theinsecure
configuration setting. A scheme ofhttp
indicates an insecure connection and takes precedence over theinsecure
configuration setting. If the gRPC client implementation does not support an endpoint with a scheme ofhttp
orhttps
then the endpoint SHOULD be transformed to the most sensible format for that implementation.- Default:
http://localhost:4317
[1] - Env vars:
OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
- Default:
-
Insecure: Whether to enable client transport security for the exporter's gRPC connection. This option only applies to OTLP/gRPC when an endpoint is provided without the
http
orhttps
scheme - OTLP/HTTP always uses the scheme provided for theendpoint
. Implementations MAY choose to not implement theinsecure
option if it is not required or supported by the underlying gRPC client implementation.- Default:
false
- Env vars:
OTEL_EXPORTER_OTLP_INSECURE
OTEL_EXPORTER_OTLP_TRACES_INSECURE
OTEL_EXPORTER_OTLP_METRICS_INSECURE
OTEL_EXPORTER_OTLP_LOGS_INSECURE
OTEL_EXPORTER_OTLP_SPAN_INSECURE
OTEL_EXPORTER_OTLP_METRIC_INSECURE
[2]
- Default:
-
Certificate File: The trusted certificate to use when verifying a server's TLS credentials. Should only be used for a secure connection.
- Default: n/a
- Env vars:
OTEL_EXPORTER_OTLP_CERTIFICATE
OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE
OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE
OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE
-
Client key file: Clients private key to use in mTLS communication in PEM format.
- Default: n/a
- Env vars:
OTEL_EXPORTER_OTLP_CLIENT_KEY
OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY
OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY
-
Client certificate file: Client certificate/chain trust for clients private key to use in mTLS communication in PEM format.
- Default: n/a
- Env vars:
OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE
OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE
OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE
-
Headers: Key-value pairs to be used as headers associated with gRPC or HTTP requests. See Specifying headers for more details.
- Default: n/a
- Env vars:
OTEL_EXPORTER_OTLP_HEADERS
OTEL_EXPORTER_OTLP_TRACES_HEADERS
OTEL_EXPORTER_OTLP_METRICS_HEADERS
OTEL_EXPORTER_OTLP_LOGS_HEADERS
-
Compression: Compression key for supported compression types. Supported compression:
gzip
.- Default: No value [2]
- Env vars:
OTEL_EXPORTER_OTLP_COMPRESSION
OTEL_EXPORTER_OTLP_TRACES_COMPRESSION
OTEL_EXPORTER_OTLP_METRICS_COMPRESSION
OTEL_EXPORTER_OTLP_LOGS_COMPRESSION
-
Timeout: Maximum time the OTLP exporter will wait for each batch export.
- Default: 10s
- Env vars:
OTEL_EXPORTER_OTLP_TIMEOUT
OTEL_EXPORTER_OTLP_TRACES_TIMEOUT
OTEL_EXPORTER_OTLP_METRICS_TIMEOUT
OTEL_EXPORTER_OTLP_LOGS_TIMEOUT
-
Protocol: The transport protocol. Options MUST be one of:
grpc
,http/protobuf
,http/json
. See Specify Protocol for more details.- Default:
http/protobuf
[3] - Env vars:
OTEL_EXPORTER_OTLP_PROTOCOL
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL
- Default:
[1]: 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).
[2]: The environment variables OTEL_EXPORTER_OTLP_SPAN_INSECURE
and OTEL_EXPORTER_OTLP_METRIC_INSECURE
are obsolete because they do not follow
the common naming scheme of the other environment variables. They are still
supported because they were part of a stable release of the specification.
Use OTEL_EXPORTER_OTLP_TRACES_INSECURE
instead of OTEL_EXPORTER_OTLP_SPAN_INSECURE
and OTEL_EXPORTER_OTLP_METRICS_INSECURE
instead of OTEL_EXPORTER_OTLP_METRIC_INSECURE
.
[3]: 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 OTEL_EXPORTER_OTLP_*COMPRESSION
options:
none
if compression is disabled.gzip
is the only specified compression method for now.
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_ENDPOINT
is used as a base URL and the signals are sent to these paths relative to that:- Traces:
v1/traces
- Metrics:
v1/metrics
. - Logs:
v1/logs
.
Non-normatively, this could be implemented by ensuring that the base URL ends with a slash and then appending the relative URLs as strings.
- Traces:
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 http
scheme
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:
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
Traces are sent to http://collector:4318/v1/traces
, metrics to
http://collector:4318/v1/metrics
and logs to http://collector:4318/v1/logs
.
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 http://collector:4318/
(/v1/traces
is only automatically added when using the non-signal-specific
environment variable) and metrics
to 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 http://collector:4318/mycollector/v1/traces
,
logs to http://collector:4318/mycollector/v1/logs
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
relative to http://collector:4318/mycollector/
.
The OTEL_EXPORTER_OTLP_PROTOCOL
, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
, and OTEL_EXPORTER_OTLP_METRICS_PROTOCOL
environment variables specify the OTLP transport protocol. Supported values:
grpc
for protobuf-encoded data using gRPC wire format over HTTP/2 connectionhttp/protobuf
for protobuf-encoded data over HTTP connectionhttp/json
for JSON-encoded data over HTTP connection
[2]: SDKs SHOULD support both grpc
and 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 http/json
.
If no configuration is provided the default transport SHOULD be http/protobuf
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
release).
The OTEL_EXPORTER_OTLP_HEADERS
, OTEL_EXPORTER_OTLP_TRACES_HEADERS
, 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.
Transient errors are defined by the OTLP protocol specification.
For OTLP/gRPC, transient errors are defined by a set of retryable gRPC status codes.
For OTLP/HTTP, transient errors are defined by:
- A set of retryable HTTP status codes received from the server.
- The scenarios described in: All other responses and OTLP/HTTP Connection.
OpenTelemetry protocol exporters SHOULD emit a User-Agent header to at a minimum identify the exporter, the language of its implementation, and the version of the exporter. For example, the Python OTLP exporter version 1.2.3 would report the following:
OTel-OTLP-Exporter-Python/1.2.3
The format of the header SHOULD follow RFC 7231. The conventions used for specifying the OpenTelemetry SDK language and version are available in the Resource semantic conventions.