跳到主要内容
版本:3.2.16.4.1

追踪 API 流量

链路追踪与指标和日志同为可观测性的三大支柱。追踪记录请求在系统各部分间的流转过程,帮助开发人员和管理员监控系统性能、发现瓶颈并改善用户体验。

本教程介绍如何使用 opentelemetry 插件配置链路追踪。该插件为网关添加追踪能力,并根据 OpenTelemetry 规范,通过 HTTP 以二进制编码的 OLTP 格式将链路数据发送给 OpenTelemetry Collector。

前置条件​

  1. 在网关组中运行一个 API 并创建路由。

安装 OpenTelemetry​

本节使用特定的 OpenTelemetry Collector,也可以使用 SigNoz OpenTelemetry Collector 等其他发行版。它们均可处理遥测数据,但关注点、功能及集成灵活性各有不同。

启动一个 OpenTelemetry Collector 实例:

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

配置 OpenTelemetry 元数据​

本节为 opentelemetry 插件配置元数据,用于指定连接接口和其他参数。

  1. 在侧边栏选择目标网关组下的 插件设置。

  2. 选择 插件元数据 标签页,然后点击 新增插件元数据。

  3. 搜索 opentelemetry 插件,然后点击 新增元数据。

  4. 在弹出的对话框中,将以下配置添加到 JSON 编辑器,并将采集器地址替换为你的 IP 地址:

    {
    "trace_id_source": "x-request-id",
    "resource": {
    "service.name": "API7"
    },
    "collector": {
    "address": "192.168.2.106:4318",
    "request_timeout": 3,
    "request_headers": {
    "Authorization": "token"
    }
    },
    "batch_span_processor": {
    "drop_on_queue_full": false,
    "max_queue_size": 1024,
    "batch_timeout": 2,
    "inactive_timeout": 1,
    "max_export_batch_size": 16
    },
    "set_ngx_var": true
    }
  5. 点击 保存。

将 OpenTelemetry 配置为全局插件​

本示例将 opentelemetry 配置为全局插件,为所有请求生成链路追踪数据。

  1. 在侧边栏选择目标网关组下的 插件设置。
  2. 选择 全局插件规则 标签页,然后点击 启用插件。
  3. 搜索 opentelemetry 插件,然后点击 启用。
  4. 在弹出的对话框中,将以下配置添加到 JSON 编辑器:
{
"opentelemetry": {
"sampler": {
"name": "always_on"
}
}
}
  1. 点击 启用。

假设你已按照发布你的第一个 API中的步骤创建示例路由。如果使用 Kubernetes,还应已创建 httpbin 上游。

向此路由发送几个请求:

curl "http://127.0.0.1:9080/ip"

在 OpenTelemetry Collector 的日志中,可以看到从网关流量采集的链路数据:

{"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 1}
{"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 1}
{"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 1}

在路由上配置 OpenTelemetry​

本示例在一条路由上配置 opentelemetry 插件,仅追踪访问该路由的请求。

  1. 打开服务,创建一个新路由或更新现有的 /ip 路由。
  2. 点击 启用插件。
  3. 搜索 opentelemetry 插件,然后点击 启用。
  4. 在弹出的对话框中,将以下配置添加到 JSON 编辑器:
{
"opentelemetry": {
"sampler": {
"name": "always_on"
}
}
}
  1. 点击 启用。

向此路由发送几个请求:

curl "http://127.0.0.1:9080/ip"

在 OpenTelemetry Collector 的日志中,可以看到从网关流量采集的链路数据:

{"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 1}
{"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 1}
{"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 1}

在网关访问日志中使用追踪变量​

本示例将更新网关的访问日志配置,以显示 OpenTelemetry 链路信息。确保插件元数据中的 set_ngx_var 已设置为 true。

在网关配置文件中更新日志格式配置:

docker exec <api7-ee-gateway-container-name> /bin/sh -c "echo '
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
' > /usr/local/apisix/conf/config.yaml"

重新加载容器,使配置变更生效:

docker exec <api7-ee-gateway-container-name> apisix reload

假设你已按照发布你的第一个 API中的步骤创建示例路由。如果使用 Kubernetes,还应已创建 httpbin 上游。

向此路由发送几个请求:

curl "http://127.0.0.1:9080/ip"

在网关日志中,可以看到类似以下内容的访问日志:

{"time": "2024-11-11T09:21:45+00:00","opentelemetry_context_traceparent": "00-3a142e5c18c01a5ff84f844f14ca8bd8-d3915c694505a6f3-01","opentelemetry_trace_id": "3a142e5c18c01a5ff84f844f14ca8bd8","opentelemetry_span_id": "d3915c694505a6f3","remote_addr": "127.0.0.1"}
{"time": "2024-11-11T09:21:46+00:00","opentelemetry_context_traceparent": "00-4766edec58af12c47eddefa775fe3cbb-fc6ca6cdd7f4d501-01","opentelemetry_trace_id": "4766edec58af12c47eddefa775fe3cbb","opentelemetry_span_id": "fc6ca6cdd7f4d501","remote_addr": "127.0.0.1"}
{"time": "2024-11-11T09:21:46+00:00","opentelemetry_context_traceparent": "00-dde5b4987a2ab2cce63559cb48945054-4def031b882e0ad2-01","opentelemetry_trace_id": "dde5b4987a2ab2cce63559cb48945054","opentelemetry_span_id": "4def031b882e0ad2","remote_addr": "127.0.0.1"}