opentelemetry

描述

OpenTelemetry 提供符合 OpenTelemetry specification 协议规范的 Tracing 数据上报。

只支持 HTTP 协议,且请求类型为 application/x-protobuf 的数据上报,相关协议标准:OTLP/HTTP Request.

属性

名称类型必选项默认值有效值描述
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”]采样算法
sampler.options.root.optionsobject可选{fraction = 0}采样算法参数
sampler.options.root.options.fractionnumber可选0[0, 1]trace_id_ratio 采样算法的百分比
additional_attributesarray[string]optional追加到 trace span 的额外属性(变量名为 key,变量值为 value)
additional_attributes[0]stringrequiredAPISIX or Nginx 变量,例如 http_header or route_id

如何启用

首先,你需要在 config.yaml 里面启用 opentelemetry 插件:

  1. # 加到 config.yaml
  2. plugins:
  3. - ... # plugin you need
  4. - opentelemetry

然后重载 APISIX。

下面是一个示例,在指定的 route 上开启了 opentelemetry 插件:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "methods": ["GET"],
  4. "uris": [
  5. "/uid/*"
  6. ],
  7. "plugins": {
  8. "opentelemetry": {
  9. "sampler": {
  10. "name": "always_on"
  11. }
  12. }
  13. },
  14. "upstream": {
  15. "type": "roundrobin",
  16. "nodes": {
  17. "10.110.149.175:8089": 1
  18. }
  19. }
  20. }'

如何设置数据上报

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

名称类型默认值描述
trace_id_sourceenumrandom合法的取值:randomx-request-id,允许使用当前请求 ID 代替随机 ID 作为新的 TraceID,必须确保当前请求 ID 是符合 TraceID 规范的:[0-9a-f]{32}
resourceobject追加到 trace 的额外 resource
collectorobject{address = “127.0.0.1:4318”, request_timeout = 3}数据采集服务
collector.addressstring127.0.0.1:4318数据采集服务地址
collector.request_timeoutinteger3数据采集服务上报请求超时时长,单位秒
collector.request_headersobject数据采集服务上报请求附加的 HTTP 请求头
batch_span_processorobjecttrace span 处理器参数配置
batch_span_processor.drop_on_queue_fullbooleantrue当处理器缓存队列慢试,丢弃新到来的 span
batch_span_processor.max_queue_sizeinteger2048处理器缓存队列容量最大值
batch_span_processor.batch_timeoutnumber5构造一批 span 超时时长,单位秒
batch_span_processor.max_export_batch_sizeinteger256一批 span 的数量,每次上报的 span 数量
batch_span_processor.inactive_timeoutnumber2每隔多长时间检查是否有一批 span 可以上报,单位秒

配置示例:

  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 插件的时候,很简单,在插件的配置中把对应的 JSON 配置删除即可,无须重启服务,即刻生效:

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