opentelemetry

本文介绍了关于 APIX opentelemetry 插件的基本信息及使用方法。

描述

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

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

属性

名称	类型	必选项	默认值	有效值	描述
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	否		{fraction = 0, root = {name = "always_off"}}	采样策略参数。
sampler.options.fraction	number	否	0	[0, 1]	trace_id_ratio 采样策略的百分比。
sampler.options.root	object	否	{name = "always_off", options = {fraction = 0}}		parent_base 采样策略在没有上游 tracing 时，会使用 root 采样策略做决策。
sampler.options.root.name	string	否	always_off	["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 的额外属性（变量名为 key，变量值为 value）。
additional_attributes[0]	string	是			APIX 或 NGINX 变量，例如：http_header 或者 route_id。

如何设置数据上报

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

名称	类型	默认值	描述
trace_id_source	enum	random	trace ID 的来源。有效值为：random 或 x-request-id。当设置为 x-request-id 时，x-request-id 头的值将用作跟踪 ID。请确保当前请求 ID 是符合 TraceID 规范的：[0-9a-f]{32}。
resource	object		追加到 trace 的额外 resource。
collector	object		OpenTelemetry Collector 配置。
collector.address	string	127.0.0.1:4318	数据采集服务的地址。如果数据采集服务使用的是 HTTPS 协议，可以将 address 设置为 https://127.0.0.1:4318。
collector.request_timeout	integer	3	数据采集服务上报请求超时时长，单位为秒。
collector.request_headers	object		数据采集服务上报请求附加的 HTTP 请求头。
batch_span_processor	object		trace span 处理器参数配置。
batch_span_processor.drop_on_queue_full	boolean	true	如果设置为 true 时，则在队列排满时删除 span。否则，强制处理批次。
batch_span_processor.max_queue_size	integer	2048	处理器缓存队列容量的最大值。
batch_span_processor.batch_timeout	number	5	构造一批 span 超时时间，单位为秒。
batch_span_processor.max_export_batch_size	integer	256	单个批次中要处理的 span 数量。
batch_span_processor.inactive_timeout	number	2	两个处理批次之间的时间间隔，单位为秒。

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

plugin_attr:
  opentelemetry:
    resource:
      service.name: APISIX
      tenant.id: business_id
    collector:
      address: 192.168.8.211:4318
      request_timeout: 3
      request_headers:
        foo: bar
    batch_span_processor:
      drop_on_queue_full: false
      max_queue_size: 6
      batch_timeout: 2
      inactive_timeout: 1
      max_export_batch_size: 2

如何启用

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

plugins:
  - ... # plugin you need
  - opentelemetry

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

curl http://127.0.0.1:9180/apix/admin/routes/1  \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uris": [
        "/uid/*"
    ],
    "plugins": {
        "opentelemetry": {
            "sampler": {
                "name": "always_on"
            }
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

禁用插件

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

curl http://127.0.0.1:9180/apix/admin/routes/1  \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uris": [
        "/uid/*"
    ],
    "plugins": {
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'