跳到主要内容

OpenTelemetry

opentelemetry 插件对 APISIX 进行插桩，并根据 OpenTelemetry 规范，以二进制编码的 OTLP over HTTP 将追踪信息发送到 OpenTelemetry 收集器。

示例​

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

启用 opentelemetry 插件​

如果你使用的是 API7 企业版，可以跳过本节，因为无需手动启用该插件。

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

config.yaml
plugins:
  - ...
  - opentelemetry

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

发送追踪到 OpenTelemetry​

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

在 Docker 中启动一个 OpenTelemetry 收集器实例：

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

收集器应开始监听 127.0.0.1:4318。如果你想更新收集器，可以配置插件元数据如下：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/opentelemetry" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "collector": {
      "address": "127.0.0.1:4318"
    }
  }'

创建一个带有 opentelemetry 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_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 收集器的日志中，你应该看到类似于以下的信息：

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"}

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

在日志记录中使用追踪变量​

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

  • opentelemetry_context_traceparent: trace parent ID
  • opentelemetry_trace_id: 当前 span 的追踪 ID
  • opentelemetry_span_id: 当前 span 的 span ID

配置插件元数据以将 set_ngx_var 设置为 true：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/opentelemetry" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "set_ngx_var": true
  }'

在 配置文件 中更新访问日志格式，以使用 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

重新加载 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"}