OpenTelemetry Protocol Exporter

Status: Stable

This document specifies the configuration options available to the OpenTelemetry Protocol (OTLP) Exporter as well as the retry behavior.

Configuration Options

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, metrics, or logs. The implementation MUST honor the following URL components:

    • scheme (http or https)
    • host
    • port
    • path

    The implementation MAY ignore all other URL components.

    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

  • Endpoint (OTLP/gRPC): Target to which the exporter is going to send spans, metrics, or logs. The option SHOULD accept any form allowed by the underlying gRPC client implementation. Additionally, the option MUST accept a URL with a scheme of either http or https. A scheme of https indicates a secure connection and takes precedence over the insecure configuration setting. A scheme of http indicates an insecure connection and takes precedence over the insecure configuration setting. If the gRPC client implementation does not support an endpoint with a scheme of http or https 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

  • 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 or https scheme - OTLP/HTTP always uses the scheme provided for the endpoint. Implementations MAY choose to not implement the insecure 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 [2]

  • 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 [3]
    • 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
    • Env vars: OTEL_EXPORTER_OTLP_PROTOCOL OTEL_EXPORTER_OTLP_TRACES_PROTOCOL OTEL_EXPORTER_OTLP_METRICS_PROTOCOL OTEL_EXPORTER_OTLP_LOGS_PROTOCOL

[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. However, if they are already implemented, they SHOULD continue to be supported as they were part of a stable release of the specification.

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

Endpoint URLs for OTLP/HTTP

Based on the environment variables above, the OTLP/HTTP exporter MUST construct URLs for each signal as follow:

  1. 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).

  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.

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

Example 1

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.

Example 2

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

Example 3

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

Specify Protocol

The OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, OTEL_EXPORTER_OTLP_METRICS_PROTOCOL and OTEL_EXPORTER_OTLP_LOGS_PROTOCOL environment variables specify the OTLP transport protocol. Supported values:

  • grpc for protobuf-encoded data using gRPC wire format over HTTP/2 connection
  • http/protobuf for protobuf-encoded data over HTTP connection
  • http/json for JSON-encoded data over HTTP connection

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

Specifying headers via environment variables

The OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_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 Baggage, except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings.

Retry

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

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:

  1. A set of retryable HTTP status codes received from the server.
  2. The scenarios described in: All other responses and OTLP/HTTP Connection.

User Agent

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.