opentelemetry

描述

opentelemetry 插件可用于根据 OpenTelemetry specification 协议规范上报 Tracing 数据。

该插件仅支持二进制编码的 OLTP over HTTP，即请求类型为 application/x-protobuf 的数据上报。

属性

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

如何设置数据上报

你可以通过在 conf/config.yaml 中指定配置来设置数据上报：

名称类型默认值描述
trace_id_sourceenumx-request-idtrace ID 的来源。有效值为：random 或 x-request-id。当设置为 x-request-id 时，x-request-id 头的值将用作跟踪 ID。请确保当前请求 ID 是符合 TraceID 规范的：[0-9a-f]{32}。
resourceobject追加到 trace 的额外 resource。
collectorobject{address = “127.0.0.1:4318”, request_timeout = 3}OpenTelemetry Collector 配置。
collector.addressstring127.0.0.1:4318数据采集服务的地址。如果数据采集服务使用的是 HTTPS 协议，可以将 address 设置为 https://127.0.0.1:4318。
collector.request_timeoutinteger3数据采集服务上报请求超时时长，单位为秒。
collector.request_headersobject数据采集服务上报请求附加的 HTTP 请求头。
batch_span_processorobjecttrace span 处理器参数配置。
batch_span_processor.drop_on_queue_fullbooleanfalse如果设置为 true 时，则在队列排满时删除 span。否则，强制处理批次。
batch_span_processor.max_queue_sizeinteger1024处理器缓存队列容量的最大值。
batch_span_processor.batch_timeoutnumber2构造一批 span 超时时间，单位为秒。
batch_span_processor.max_export_batch_sizeinteger16单个批次中要处理的 span 数量。
batch_span_processor.inactive_timeoutnumber1两个处理批次之间的时间间隔，单位为秒。
opentelemetry - 图1note

如果你在 error log 中发现由 hex2bytes 函数引发的 bad argument #1 to '?' (invalid value) 错误，务必确认你的 traceId 是否满足 opentelemetry 的 traceId 格式 所需的正则规范[0-9a-f]{32}。

例如，当插件属性 trace_id_source 配置为 x-request-id 时，如果请求包含由 Envoy 生成的 x-request-id 请求头，可能会发生上述情况。Envoy 默认使用 UUID 生成该请求头。当 opentelemetry 插件将此 UUID 作为 traceId 时，UUID 中的 - 可能会引起问题。由于带有 - 的 UUID 格式与 traceId 格式不符，因此尝试将跟踪推送到收集器时会导致错误。

你可以参考以下示例进行配置：

./conf/config.yaml

  1. plugin_attr:
  2.   opentelemetry:
  3.     resource:
  4.       service.name: APISIX
  5.       tenant.id: business_id
  6.     collector:
  7.       address: 192.168.8.211:4318
  8.       request_timeout: 3
  9.       request_headers:
  10.         foo: bar
  11.     batch_span_processor:
  12.       drop_on_queue_full: false
  13.       max_queue_size: 6
  14.       batch_timeout: 2
  15.       inactive_timeout: 1
  16.       max_export_batch_size: 2

如何使用变量

以下nginx变量是由opentelemetry 设置的。

  • opentelemetry_context_traceparent - W3C trace context, 例如：00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01
  • opentelemetry_trace_id - 当前 span 的 trace_id
  • opentelemetry_span_id - 当前 span 的 span_id

如何使用？你需要在配置文件（./conf/config.yaml）设置如下：

./conf/config.yaml

  1. http:
  2.     enable_access_log: true
  3.     access_log: "/dev/stdout"
  4.     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","uri": "$uri"}'
  5.     access_log_format_escape: json
  6. plugins:
  7.   - opentelemetry
  8. plugin_attr:
  9.   opentelemetry:
  10.     set_ngx_var: true

如何启用

opentelemetry 插件默认为禁用状态，你需要在配置文件（./conf/config.yaml）中开启该插件：

./conf/config.yaml

  1. plugins:
  2.   - ... # plugin you need
  3.   - opentelemetry

开启成功后，可以通过如下命令在指定路由上启用 opentelemetry 插件：

opentelemetry - 图2note

您可以这样从 config.yaml 中获取 admin_key 并存入环境变量：

  1. admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
  1. curl http://127.0.0.1:9180/apisix/admin/routes/1  \
  2. -H "X-API-KEY: $admin_key" -X PUT -d '
  3. {
  4.     "methods": ["GET"],
  5.     "uris": [
  6.         "/uid/*"
  7.     ],
  8.     "plugins": {
  9.         "opentelemetry": {
  10.             "sampler": {
  11.                 "name": "always_on"
  12.             }
  13.         }
  14.     },
  15.     "upstream": {
  16.         "type": "roundrobin",
  17.         "nodes": {
  18.             "127.0.0.1:1980": 1
  19.         }
  20.     }
  21. }'

删除插件

当你需要禁用 opentelemetry 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1  \
  2. -H "X-API-KEY: $admin_key" -X PUT -d '
  3. {
  4.     "methods": ["GET"],
  5.     "uris": [
  6.         "/uid/*"
  7.     ],
  8.     "plugins": {
  9.     },
  10.     "upstream": {
  11.         "type": "roundrobin",
  12.         "nodes": {
  13.             "127.0.0.1:1980": 1
  14.         }
  15.     }
  16. }'