# OpenTelemetry 配置选项

OpenTelemetry 插件通过 OTLP/HTTP 将采样后的 APISIX 和 API7 网关请求链路导出到 OpenTelemetry Collector，用于分布式追踪。<!-- --> <!-- -->配置涵盖插件参数和插件元数据。

## 参数[​](#parameters "参数的直接链接")

请参阅插件[通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)，了解所有插件通用的配置选项。

* sampler

  object

  ***

  采样配置。

  * name

    string

    默认值：`always_off`

    有效值：

    `always_on`、`always_off`、`trace_id_ratio` 或 `parent_base`

    ***

    采样策略。

    要始终采样，请使用 `always_on`。

    要从不采样，请使用 `always_off`。

    要根据给定比例随机采样，请使用 `trace_id_ratio`。

    要遵循父跨度的采样决策，请使用 `parent_base`。如果没有父跨度，则由根采样器决定是否采样。

  * options

    object

    ***

    采样策略的参数。

    * fraction

      number

      默认值：`0`

      ***

      采样策略为 `trace_id_ratio` 时的采样比例。小于 `0` 的值按 `0` 处理，大于或等于 `1` 的值会对所有链路采样。

    * root

      object

      ***

      采样策略为 `parent_base` 且跨度没有父跨度时使用的根采样器。

      * name

        string

        默认值：`always_off`

        有效值：

        `always_on`、`always_off` 或 `trace_id_ratio`

        ***

        根采样策略。

      * options

        object

        ***

        根采样策略参数。

        * fraction

          number

          默认值：`0`

          ***

          根采样策略为 `trace_id_ratio` 时的采样比例。小于 `0` 的值按 `0` 处理，大于或等于 `1` 的值会对所有链路采样。

* additional\_attributes

  array\[string]

  ***

  要作为字符串属性附加到链路跨度的[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)名称。变量值在日志阶段解析，因此可以使用请求处理后期才填充的变量。数字和布尔值会转换为字符串；布尔值 `false` 不会被丢弃。

* additional\_header\_prefix\_attributes

  array\[string]

  ***

  在日志阶段作为字符串属性附加到链路跨度的请求头或请求头前缀。例如，使用 `x-my-header` 或 `x-my-headers-*` 来包含所有前缀为 `x-my-headers-` 的请求头。同一请求头的多个值使用 `,` 连接。

## 插件元数据[​](#plugin-metadata "插件元数据的直接链接")

* trace\_id\_source

  string

  默认值：`random`

  有效值：

  `x-request-id` 或 `random`

  ***

  链路 ID 的来源。使用 `x-request-id` 时，请提供一个非零的 32 字符十六进制链路 ID。APISIX 3.18.0 和 API7 网关 3.10.7 会规范化并验证候选值；无效时会改用生成的链路 ID。API7 网关 3.9.20 不验证显式提供的请求头；请求头缺失时使用 NGINX 请求 ID。

* resource

  object

  ***

  添加到每个跨度的资源属性，例如 `{"service.name": "APISIX"}`。如果对象存在但未设置 `service.name`，插件会添加 `service.name: APISIX`。

* collector

  object

  ***

  收集器配置。

  * address

    string

    默认值：`127.0.0.1:4318`

    ***

    OpenTelemetry Collector 的基础地址。地址不含协议时，插件会使用 HTTP 并追加 `/v1/traces`。

  * request\_timeout

    integer

    默认值：`3`

    ***

    发送到 OpenTelemetry Collector 的请求超时时间（秒）。

  * request\_headers

    object

    ***

    向 OpenTelemetry Collector 发送链路时包含的请求头，例如 `{"Authorization": "token"}`。

* batch\_span\_processor

  object

  ***

  批量跨度处理器配置。

  * drop\_on\_queue\_full

    boolean

    默认值：`true`

    ***

    如果为 true，则在队列已满时丢弃新跨度；如果为 false，则处理队列中的批次以腾出空间。

  * max\_queue\_size

    integer

    默认值：`2048`

    有效值：

    大于 `max_export_batch_size`

    ***

    为延迟处理缓冲的最大跨度数。

  * batch\_timeout

    number

    默认值：`5`

    有效值：

    大于 0

    ***

    构建批次时允许等待的最长时间（秒）。

  * inactive\_timeout

    number

    默认值：`2`

    有效值：

    大于 0

    ***

    队列未满时处理队列中批次的时间间隔（秒）。

  * max\_export\_batch\_size

    integer

    默认值：`256`

    有效值：

    大于 0 且小于 `max_queue_size`

    ***

    单个导出批次中处理的最大跨度数。

* set\_ngx\_var

  boolean

  默认值：`false`

  ***

  如果为 true，则填充 `opentelemetry_context_traceparent`、`opentelemetry_trace_id` 和 `opentelemetry_span_id` NGINX 变量。
