OpenTelemetry Protocol Exporter

状态: 稳定

本文档指定了 OpenTelemetry Protocol (OTLP) Exporter 可用的配置选项以及重试行为。

配置选项

以下配置选项必须可用于配置 OTLP exporter。每个配置选项必须可被特定信号的选项覆盖。

  • 端点 (OTLP/HTTP)：Exporter 将会发送 spans、metrics 或 logs 的目标 URL。实现必须遵守以下 URL 组件

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

    实现可以选择忽略所有其他 URL 组件。

    https 协议表示安全连接。当使用 OTEL_EXPORTER_OTLP_ENDPOINT 时，Exporter 必须按照 下文所述 的方式构造每个信号的 URL。特定信号的端点配置选项具有优先权，并可用于覆盖此行为（这些配置直接按原样使用 URL，不做任何修改）。有关更多详细信息，请参阅 OTLP 规范。

    • 默认值：https://:4318 [1]
    • 环境变量：OTEL_EXPORTER_OTLP_ENDPOINT OTEL_EXPORTER_OTLP_TRACES_ENDPOINT OTEL_EXPORTER_OTLP_METRICS_ENDPOINT OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
    • 类型：String

  • 端点 (OTLP/gRPC)：Exporter 将会发送 spans、metrics 或 logs 的目标。该选项应接受底层 gRPC 客户端实现允许的任何形式。此外，该选项必须接受一个具有 http 或 https 协议的 URL。https 协议表示安全连接，并优先于 insecure 配置设置。http 协议表示不安全连接，并优先于 insecure 配置设置。如果 gRPC 客户端实现不支持带有 http 或 https 协议的端点，则应将该端点转换为该实现最合适的格式。

    • 默认值：https://:4317 [1]
    • 环境变量：OTEL_EXPORTER_OTLP_ENDPOINT OTEL_EXPORTER_OTLP_TRACES_ENDPOINT OTEL_EXPORTER_OTLP_METRICS_ENDPOINT OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
    • 类型：String

  • 不安全：是否为 Exporter 的 gRPC 连接启用客户端传输安全。此选项仅适用于未提供 http 或 https 协议的端点的 OTLP/gRPC - OTLP/HTTP 始终使用为 endpoint 提供的协议。如果底层 gRPC 客户端实现不要求或不支持 insecure 选项，实现可以选择不实现此选项。

    • 默认值：false
    • 环境变量：OTEL_EXPORTER_OTLP_INSECURE OTEL_EXPORTER_OTLP_TRACES_INSECURE OTEL_EXPORTER_OTLP_METRICS_INSECURE OTEL_EXPORTER_OTLP_LOGS_INSECURE [2]
    • 类型：Boolean

  • 证书文件：用于验证服务器 TLS 凭证的可信证书。仅应用于安全连接。

    • 默认值：n/a
    • 环境变量：OTEL_EXPORTER_OTLP_CERTIFICATE OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE
    • 类型：String

  • 客户端密钥文件：用于 mTLS 通信的 PEM 格式客户端私钥。

    • 默认值：n/a
    • 环境变量：OTEL_EXPORTER_OTLP_CLIENT_KEY OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY
    • 类型：String

  • 客户端证书文件：用于 mTLS 通信的 PEM 格式客户端证书/证书链信任，用于客户端私钥。

    • 默认值：n/a
    • 环境变量：OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE
    • 类型：String

  • Headers：与 gRPC 或 HTTP 请求关联的键值对。有关更多详细信息，请参阅 指定 Headers。

    • 默认值：n/a
    • 环境变量：OTEL_EXPORTER_OTLP_HEADERS OTEL_EXPORTER_OTLP_TRACES_HEADERS OTEL_EXPORTER_OTLP_METRICS_HEADERS OTEL_EXPORTER_OTLP_LOGS_HEADERS
    • 类型：String

  • 压缩：支持的压缩类型的压缩键。支持的压缩：gzip。

    • 默认值：无值 [3]
    • 环境变量：OTEL_EXPORTER_OTLP_COMPRESSION OTEL_EXPORTER_OTLP_TRACES_COMPRESSION OTEL_EXPORTER_OTLP_METRICS_COMPRESSION OTEL_EXPORTER_OTLP_LOGS_COMPRESSION
    • 类型：Enum

  • 超时：OTLP Exporter 等待每个批量导出的最长时间。

    • 默认值：10s
    • 环境变量：OTEL_EXPORTER_OTLP_TIMEOUT OTEL_EXPORTER_OTLP_TRACES_TIMEOUT OTEL_EXPORTER_OTLP_METRICS_TIMEOUT OTEL_EXPORTER_OTLP_LOGS_TIMEOUT
    • 类型：Timeout

  • 协议：传输协议。选项必须是以下之一：grpc、http/protobuf、http/json。有关更多详细信息，请参阅 指定协议。

    • 默认值：http/protobuf [4]
    • 环境变量：OTEL_EXPORTER_OTLP_PROTOCOL OTEL_EXPORTER_OTLP_TRACES_PROTOCOL OTEL_EXPORTER_OTLP_METRICS_PROTOCOL OTEL_EXPORTER_OTLP_LOGS_PROTOCOL
    • 类型：Enum

[1]：SDK 应默认端点变量使用 http 协议，除非有充分理由选择 https 协议作为默认值（例如，为了在稳定的 SDK 版本中向后兼容）。

[2]：环境变量 OTEL_EXPORTER_OTLP_SPAN_INSECURE 和 OTEL_EXPORTER_OTLP_METRIC_INSECURE 已废弃，因为它们不遵循其他环境变量的通用命名约定。但是，如果它们已被实现，则应继续支持它们，因为它们是规范稳定版本的一部分。

[3]：如果没有明确指定压缩值，SIGs 可以根据其认为最有利的选项作为默认值。这在存在技术限制时尤为重要，例如，直接从移动设备向后端服务器发送遥测数据。

[4]：默认协议应为 http/protobuf，除非 SDK 有充分理由选择 grpc 作为默认值。例如，为了保持向后兼容性，如果 grpc 在稳定的 SDK 版本中已是默认值，则可能需要将其保留为默认值。

OTEL_EXPORTER_OTLP_*COMPRESSION 选项的受支持值

  • none，如果禁用压缩。
  • gzip 是目前唯一指定的压缩方法。

OTLP/HTTP 的端点 URL

根据上述环境变量，OTLP/HTTP Exporter 必须为每个信号构造如下 URL

  1. 对于特定信号的变量（OTEL_EXPORTER_OTLP_<signal>_ENDPOINT），URL 必须按原样使用，不做任何修改。唯一的例外是，如果 URL 不包含路径部分，则必须使用根路径 /（参见 示例 2）。

  2. 如果发送的信号没有上述的特定信号配置，则 OTEL_EXPORTER_OTLP_ENDPOINT 用作基本 URL，信号被发送到相对于该 URL 的路径：

    • Traces: v1/traces
    • Metrics: v1/metrics。
    • Logs: v1/logs。

    非规范性地，这可以通过确保基本 URL 以斜杠结尾，然后将相对 URL 作为字符串附加来实现。

SDK 不得以除上述以外的任何方式修改 URL。这意味着，如果端口为空或未提供，对于 http 协议，TCP 端口 80 是默认值，对于 https 协议，TCP 端口 443 是默认值，这符合这些协议的常规规则（RFC 7230）。

示例 1

以下配置将所有信号发送到同一个 Collector

export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318

Traces 发送到 http://collector:4318/v1/traces，Metrics 发送到 http://collector:4318/v1/metrics，Logs 发送到 http://collector:4318/v1/logs。

示例 2

Traces 和 Metrics 发送到不同的 Collector 和路径

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://collector:4318
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://collector.example.com/v1/metrics

这将把 traces 直接发送到根路径 http://collector:4318/（/v1/traces 仅在未使用特定信号的环境变量时才自动添加），并将 metrics 发送到 https://collector.example.com/v1/metrics，使用默认的 https 端口（443）。

示例 3

以下配置将除 metrics 之外的所有信号发送到同一个 Collector

export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318/mycollector/
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://collector.example.com/v1/metrics/

Traces 发送到 http://collector:4318/mycollector/v1/traces，Logs 发送到 http://collector:4318/mycollector/v1/logs，Metrics 发送到 https://collector.example.com/v1/metrics/，使用默认的 https 端口（443）。其他信号（如果存在）将发送到相对于 http://collector:4318/mycollector/ 的特定路径。

指定协议

OTEL_EXPORTER_OTLP_PROTOCOL、OTEL_EXPORTER_OTLP_TRACES_PROTOCOL、OTEL_EXPORTER_OTLP_METRICS_PROTOCOL 和 OTEL_EXPORTER_OTLP_LOGS_PROTOCOL 环境变量指定 OTLP 传输协议。支持的值：

  • grpc，用于通过 HTTP/2 连接上的 gRPC 格式进行 Protobuf 编码的数据
  • http/protobuf，用于通过 HTTP 连接进行 Protobuf 编码的数据
  • http/json，用于通过 HTTP 连接进行 JSON 编码的数据

SDK 应支持 grpc 和 http/protobuf 传输，并且必须支持其中至少一种。如果仅支持一种，则应为 http/protobuf。它们也可以支持 http/json。

如果没有提供配置，默认传输应为 http/protobuf，除非 SDK 有充分理由选择 grpc 作为默认值（例如，为了向后兼容，如果 grpc 之前是稳定 SDK 版本中的默认值）。

通过环境变量指定 Headers

OTEL_EXPORTER_OTLP_HEADERS、OTEL_EXPORTER_OTLP_TRACES_HEADERS、OTEL_EXPORTER_OTLP_METRICS_HEADERS、OTEL_EXPORTER_OTLP_LOGS_HEADERS 环境变量将包含键值对列表，这些键值对应按照 W3C Baggage 的格式表示，不同之处在于不支持额外的分号分隔的元数据，即：key1=value1,key2=value2。所有属性值都必须被视为字符串。

重试

必须使用重试策略处理瞬时错误。此重试策略必须实现指数退避和抖动，以避免在网络恢复或目标恢复之前使目标过载。

瞬时错误

瞬时错误由 OTLP 协议规范 定义。

对于 OTLP/gRPC，瞬时错误由一组 可重试的 gRPC 状态码 定义。

对于 OTLP/HTTP，瞬时错误由以下定义：

  1. 服务器返回的一组 可重试的 HTTP 状态码。
  2. 在 所有其他响应 和 OTLP/HTTP 连接 中描述的场景。

用户代理

OpenTelemetry 协议 Exporter 应至少发送一个 User-Agent 标头，以标识 Exporter、其实现语言和 Exporter 的版本。例如，Python OTLP Exporter 版本 1.2.3 会报告以下信息：

OTel-OTLP-Exporter-Python/1.2.3

该标头的格式应遵循 RFC 7231。用于指定 OpenTelemetry SDK 语言和版本的约定可在 Resource 语义约定 中找到。

Exporter 可以公开一个配置选项来向 User-Agent 标头添加产品标识符。最终的 User-Agent 应包含 Exporter 的默认 User-Agent 字符串。目的是支持 OpenTelemetry SDK/Agent 分发版 的标识符。通常，Exporter 会将给定的标识符前置到其自身的标识符。例如：

MyDistribution/x.y.z OTel-OTLP-Exporter-Python/1.2.3