Version: Next

opentelemetry

描述#

opentelemetry 插件可用于根据 OpenTelemetry Specification 协议规范上报 Traces 数据。该插件仅支持二进制编码的 OLTP over HTTP，即请求类型为 application/x-protobuf 的数据上报。

静态配置#

默认情况下，服务名称、租户 ID、collector 和 batch span processor 的配置已预配置在默认配置中。

要自定义这些值，请将相应的配置添加到 config.yaml 中。例如：

plugin_attr:
  opentelemetry:
    trace_id_source: x-request-id     # 指定追踪 ID 的来源，`x-request-id` 或 `random`。当设置为 `x-request-id` 时，
                                      # `x-request-id` 头的值将用作追踪 ID。
    resource:                         # 追加到追踪的额外资源。
      service.name: APISIX            # 为 OpenTelemetry 追踪设置服务名称。
    collector:
      address: 127.0.0.1:4318       # 设置要发送追踪的 OpenTelemetry 收集器的地址。
      request_timeout: 3            # 设置请求 OpenTelemetry 收集器的超时时间（秒）。
      request_headers:              # 设置请求 OpenTelemetry 收集器时要包含的头信息。
        Authorization: token        # 设置授权头以包含访问令牌。
    batch_span_processor:           # 追踪跨度处理器。
      drop_on_queue_full: false     # 当导出队列满时丢弃跨度。
      max_queue_size: 1024          # 设置跨度导出队列的最大大小。
      batch_timeout: 2              # 设置跨度批次在导出队列中等待的超时时间，
                                    # 然后发送。
      inactive_timeout: 1           # 设置跨度在导出队列中等待的超时时间，如果队列不满，则发送。
      max_export_batch_size: 16     # 设置每个批次发送到 OpenTelemetry 收集器的跨度的最大数量。
    set_ngx_var: false              # 将 opentelemetry 变量导出到 nginx 变量。

重新加载 APISIX 以使更改生效。

属性#

名称	类型	必选项	默认值	有效值	描述
sampler	object	否	-	-	采样策略。
sampler.name	string	否	`always_off`	["always_on", "always_off", "trace_id_ratio", "parent_base"]	采样策略。 `always_on`：全采样；`always_off`：不采样；`trace_id_ratio`：基于 trace id 的百分比采样；`parent_base`：如果存在 tracing 上游，则使用上游的采样决定，否则使用配置的采样策略决策。
sampler.options	object	否	-	-	采样策略参数。
sampler.options.fraction	number	否	0	[0, 1]	`trace_id_ratio`：采样策略的百分比。
sampler.options.root	object	否	-	-	`parent_base`：采样策略在没有上游 tracing 时，会使用 root 采样策略做决策。
sampler.options.root.name	string	否	-	["always_on", "always_off", "trace_id_ratio"]	root 采样策略。
sampler.options.root.options	object	否	-	-	root 采样策略参数。
sampler.options.root.options.fraction	number	否	0	[0, 1]	`trace_id_ratio` root 采样策略的百分比
additional_attributes	array[string]	否	-	-	追加到 trace span 的额外属性，支持内置 NGINX 或 APISIX 变量。
additional_header_prefix_attributes	array[string]	否	-	-	附加到跟踪范围属性的标头或标头前缀。例如，使用 `x-my-header"` 或 `x-my-headers-*` 来包含带有前缀 `x-my-headers-` 的所有标头。

示例#

以下示例展示了如何在不同场景下使用 opentelemetry 插件。

启用 opentelemetry 插件#

默认情况下，APISIX 中的 opentelemetry 插件是禁用的。要启用它，请将插件添加到配置文件中，如下所示：

config.yaml

plugins:
  - ...
  - opentelemetry

重新加载 APISIX 以使更改生效。

有关 config.yaml 中可以配置的其他选项，请参阅静态配置。

将 Traces 上报到 OpenTelemetry#

以下示例展示了如何追踪对路由的请求并将 traces 发送到 OpenTelemetry。

在 Docker 启动一个 OpenTelemetry collector 实例：

docker run -d --name otel-collector -p 4318:4318 otel/opentelemetry-collector-contrib

创建一个开启了 opentelemetry 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "otel-tracing-route",
    "uri": "/anything",
    "plugins": {
      "opentelemetry": {
        "sampler": {
          "name": "always_on"
        }
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org": 1
      }
    }
  }'

向路由发送请求：

curl "http://127.0.0.1:9080/anything"

你应该收到一个 HTTP/1.1 200 OK 响应。

在 OpenTelemetry collector 的日志中，你应该看到类似以下的信息：

2024-02-18T17:14:03.825Z info ResourceSpans #0
Resource SchemaURL:
Resource attributes:
    -> telemetry.sdk.language: Str(lua)
    -> telemetry.sdk.name: Str(opentelemetry-lua)
    -> telemetry.sdk.version: Str(0.1.1)
    -> hostname: Str(e34673e24631)
    -> service.name: Str(APISIX)
ScopeSpans #0
ScopeSpans SchemaURL:
InstrumentationScope opentelemetry-lua
Span #0
    Trace ID       : fbd0a38d4ea4a128ff1a688197bc58b0
    Parent ID      :
    ID             : af3dc7642104748a
    Name           : GET /anything
    Kind           : Server
    Start time     : 2024-02-18 17:14:03.763244032 +0000 UTC
    End time       : 2024-02-18 17:14:03.920229888 +0000 UTC
    Status code    : Unset
    Status message :
Attributes:
    -> net.host.name: Str(127.0.0.1)
    -> http.method: Str(GET)
    -> http.scheme: Str(http)
    -> http.target: Str(/anything)
    -> http.user_agent: Str(curl/7.64.1)
    -> apisix.route_id: Str(otel-tracing-route)
    -> apisix.route_name: Empty()
    -> http.route: Str(/anything)
    -> http.status_code: Int(200)
{"kind": "exporter", "data_type": "traces", "name": "debug"}

要可视化这些追踪，你可以将 traces 导出到后端服务，例如 Zipkin 和 Prometheus。有关更多详细信息，请参阅exporters。

在日志中使用 trace 变量#

以下示例展示了如何配置 opentelemetry 插件以设置以下内置变量，这些变量可以在日志插件或访问日志中使用：

opentelemetry_context_traceparent: W3C trace context
opentelemetry_trace_id: 当前 span 的 trace_id
opentelemetry_span_id: 当前 span 的 span_id

如下更新配置文件。你应该自定义访问日志格式以使用 opentelemetry 插件变量，并在 set_ngx_var 字段中设置 opentelemetry 变量。

conf/config.yaml

nginx_config:
  http:
    enable_access_log: true
    access_log_format: '{"time": "$time_iso8601","opentelemetry_context_traceparent": "$opentelemetry_context_traceparent","opentelemetry_trace_id": "$opentelemetry_trace_id","opentelemetry_span_id": "$opentelemetry_span_id","remote_addr": "$remote_addr"}'
    access_log_format_escape: json
plugin_attr:
  opentelemetry:
    set_ngx_var: true

重新加载 APISIX 以使配置更改生效。

{"time": "18/Feb/2024:15:09:00 +0000","opentelemetry_context_traceparent": "00-fbd0a38d4ea4a128ff1a688197bc58b0-8f4b9d9970a02629-01","opentelemetry_trace_id": "fbd0a38d4ea4a128ff1a688197bc58b0","opentelemetry_span_id": "af3dc7642104748a","remote_addr": "172.10.0.1"}