追踪 API 流量
链路追踪与指标和日志同为可观测性的三大支柱。追踪记录请求在系统各部分间的流转过程,帮助开发人员和管理员监控系统性能、发现瓶颈并改善用户体验。
本教程介绍如何使用 opentelemetry 插件配置链路追踪。该插件为网关添加追踪能力,并根据 OpenTelemetry 规范,通过 HTTP 以二进制编码的 OLTP 格式将链路数据发送给 OpenTelemetry Collector。
前置条件
安装 OpenTelemetry
本节使用特定的 OpenTelemetry Collector,也可以使用 SigNoz OpenTelemetry Collector 等其他发行版。它们均可处理遥测数据,但关注点、功能及集成灵活性各有不同。
- Docker
- Kubernetes
启动一个 OpenTelemetry Collector 实例:
docker run -d --name otel-collector -p 4318:4318 otel/opentelemetry-collector-contrib
安装依赖项 cert-manager:
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml
安装 OpenTelemetry Operator:
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
安装一个 OpenTelemetry 实例:
kubectl apply -f - <<EOF
apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
name: simplest
spec:
config: |
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
exporters:
debug:
service:
pipelines:
traces:
receivers: [otlp]
processors: []
exporters: [debug]
EOF
配置 OpenTelemetry 元数据
本节为 opentelemetry 插件配置元数据,用于指定连接接口和其他参数。
- 控制台
- ADC
- Ingress Controller
-
在侧边栏选择目标网关组下的 插件设置。
-
选择 插件元数据 标签页,然后点击 新增插件元数据。
-
搜索
opentelemetry插件,然后点击 新增元数据。 -
在弹出的对话框中,将以下配置添加到 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} -
点击 保存。
如需使用 ADC 更新插件元数据,请创建以下配置:
plugin_metadata:
opentelemetry:
batch_span_processor:
batch_timeout: 2
drop_on_queue_full: false
inactive_timeout: 1
max_export_batch_size: 16
max_queue_size: 1024
collector:
address: 192.168.2.106:4318
request_headers:
Authorization: token
request_timeout: 3
resource:
service.name: API7
set_ngx_var: true
trace_id_source: x-request-id
将配置同步到 API7 企业版:
adc sync -f otel-metadata.yaml
创建 ConfigMap:
apiVersion: v1
kind: ConfigMap
metadata:
name: otel
data:
config.yaml: |
- cluster: default
plugins:
- name: opentelemetry
metadata:
trace_id_source: x-request-id
resource:
service.name: API7
collector:
address: simplest-collector: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
❶ 配置 ConfigMap 的名称。
❷ 配置 OpenTelemetry Collector 的地址,其中 simplest-collector 为服务名称。请根据应用的实际情况调整。
❸ 将 OpenTelemetry 变量导出为内置变量,以便在访问日志中使用。
将 ConfigMap 应用到集群:
kubectl apply -f otel-cm.yaml
在控制台打开 Ingress Controller 网关组,点击右上角的 操作,然后选择 重新生成部署脚本。复制脚本,手动加入 config.pluginMetadataCM=otel 参数并执行命令升级 Chart,将 ConfigMap 应用到 Ingress Controller。命令如下所示:
helm repo add api7 https://charts.api7.ai
helm repo update
helm upgrade --install api7-ingress api7/api7-ingress-controller \
--set "config.dashboard.adminKey=YOUR_DASHBOARD_ADMIN_KEY" \
--set "config.dashboard.baseURL=https://192.168.2.103:7443"
--set "config.pluginMetadataCM=otel"
回到控制台的 插件设置 > 插件元数据,即可看到已更新的 opentelemetry 插件及其元数据。
将 OpenTelemetry 配置为全局插件
本示例将 opentelemetry 配置为全局插件,为所有请求生成链路追踪数据。
- 控制台
- ADC
- Ingress Controller
- 在侧边栏选择目标网关组下的 插件设置。
- 选择 全局插件规则 标签页,然后点击 启用插件。
- 搜索
opentelemetry插件,然后点击 启用。 - 在弹出的对话框中,将以下配置添加到 JSON 编辑器:
{
"opentelemetry": {
"sampler": {
"name": "always_on"
}
}
}
- 点击 启用。
如需使用 ADC 配置全局插件,请创建以下配置:
global_rules:
opentelemetry:
_meta:
disable: false
opentelemetry:
sampler:
name: always_on
将配置同步到 API7 企业版:
adc sync -f otel-global-plugin otel-metadata.yaml
创建 Kubernetes 清单,使用 ApisixGlobalRule 自定义资源配置 opentelemetry 插件:
apiVersion: apisix.apache.org/v2
kind: ApisixGlobalRule
metadata:
# namespace: api7 # replace with your namespace
name: global-obs-otel
spec:
plugins:
- name: opentelemetry
enable: true
config:
sampler:
name: always_on
将配置应用到集群:
kubectl apply -f global-rule-otel.yaml
应用配置后,可在控制台的 插件设置 中看到 opentelemetry 插件。
假设你已按照发布你的第一个 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 插件,仅追踪访问该路由的请求。
- 控制台
- ADC
- Ingress Controller
- 打开服务,创建一个新路由或更新现有的
/ip路由。 - 点击 启用插件。
- 搜索
opentelemetry插件,然后点击 启用。 - 在弹出的对话框中,将以下配置添加到 JSON 编辑器:
{
"opentelemetry": {
"sampler": {
"name": "always_on"
}
}
}
- 点击 启用。
如需使用 ADC 更新全局插件,请创建以下配置:
services:
- name: httpbin
upstream:
name: httpbin
scheme: http
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 100
routes:
- uris:
- /ip
name: get-ip
methods:
- GET
plugins:
opentelemetry:
_meta:
disable: false
opentelemetry:
sampler:
name: always_on
将配置同步到 API7 企业版:
adc sync -f otel-route.yaml otel-metadata.yaml
创建 Kubernetes 清单,使用 ApisixRoute 自定义资源在路由上配置 opentelemetry 插件:
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
name: route-otel
# namespace: api7 # replace with your namespace
spec:
http:
- name: get-ip
match:
paths:
- /ip
backends:
- serviceName: httpbin
servicePort: 80
plugins:
- name: opentelemetry
enable: true
config:
sampler:
name: always_on
将配置应用到集群:
kubectl apply -f route-otel.yaml
应用配置后,可在对应的 路由 中看到 opentelemetry 插件。
向此路由发送几个请求:
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
- Kubernetes
在网关配置文件中更新日志格式配置:
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
在网关的 ConfigMap 中更新日志格式配置:
kubectl edit cm api7-ee-3-gateway
以下参数应该已经存在,但初始值不同。将相应字段更新为以下值:
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
保存 ConfigMap 并重启资源:
kubectl rollout restart deployment api7-ee-3-gateway
假设你已按照发布你的第一个 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"}