opentelemetry

描述

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

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

属性

名称类型必选项默认值有效值描述
samplerobject采样策略。
sampler.namestringalways_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.fractionnumber0[0, 1]trace_id_ratio 采样策略的百分比。
sampler.options.rootobject{name = “always_off”, options = {fraction = 0}}parent_base 采样策略在没有上游 tracing 时,会使用 root 采样策略做决策。
sampler.options.root.namestringalways_off[“always_on”, “always_off”, “trace_id_ratio”]root 采样策略。
sampler.options.root.optionsobject{fraction = 0}root 采样策略参数。
sampler.options.root.options.fractionnumber0[0, 1]trace_id_ratio root 采样策略的百分比
additional_attributesarray[string]追加到 trace span 的额外属性(变量名为 key,变量值为 value)。
additional_attributes[0]stringAPISIX 或 NGINX 变量,例如:http_header 或者 route_id

如何设置数据上报

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

名称类型默认值描述
trace_id_sourceenumrandomtrace ID 的来源。有效值为:randomx-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_fullbooleantrue如果设置为 true 时,则在队列排满时删除 span。否则,强制处理批次。
batch_span_processor.max_queue_sizeinteger2048处理器缓存队列容量的最大值。
batch_span_processor.batch_timeoutnumber5构造一批 span 超时时间,单位为秒。
batch_span_processor.max_export_batch_sizeinteger256单个批次中要处理的 span 数量。
batch_span_processor.inactive_timeoutnumber2两个处理批次之间的时间间隔,单位为秒。

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

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

如何启用

opentelemetry 插件默认为禁用状态,你需要在配置文件(./conf/config.yaml)中开启该插件:

./conf/config.yaml

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

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

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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. }'