使用 Zipkin 追踪请求

追踪是可观测性的三大支柱之一，另外两个是指标和日志。追踪跟踪请求穿越系统各个部分的旅程。它是一种有效的机制，可以帮助开发人员和管理员监控系统性能、识别瓶颈并改善用户体验。

本指南将引导你完成如何使用 zipkin 插件追踪对 APISIX 的请求并将追踪发送到 Zipkin。

前置条件

安装 Docker。
安装 cURL 以向服务发送请求进行验证。
按照快速入门教程在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。

启动 Zipkin 实例

启动一个 Zipkin 实例：

Docker
Kubernetes

docker run -d --name zipkin -p 9411:9411 openzipkin/zipkin

为 Zipkin 创建一个 Kubernetes 清单文件：

zipkin.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: ingress-apisix
  name: zipkin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: zipkin
  template:
    metadata:
  namespace: ingress-apisix
      labels:
        app: zipkin
    spec:
      containers:
        - name: zipkin
          image: openzipkin/zipkin
          ports:
            - containerPort: 9411
---
apiVersion: v1
kind: Service
metadata:
  namespace: ingress-apisix
  name: zipkin
spec:
  selector:
    app: zipkin
  ports:
    - name: http
      port: 9411
      targetPort: 9411
  type: ClusterIP

将配置应用到你的集群：

kubectl apply -f zipkin.yaml

将 Zipkin Web UI 的服务端口转发到你的本地机器端口：

kubectl port-forward svc/zipkin 9411:9411 &

配置 APISIX

全局启用 zipkin 并创建一个示例路由以生成追踪。或者，你可以在路由上启用该插件。

Admin API
ADC
Ingress Controller

将 zipkin 配置为全局插件：

curl "http://127.0.0.1:9180/apisix/admin/global_rules/zipkin" -X PUT -d '
{
  "plugins": {
    "zipkin": {
      // Annotate 1
      "endpoint": "http://192.168.42.145:9411/api/v2/spans",
      // Annotate 2
      "sample_ratio": 1
    }
  }
}'

❶ 设置为 /spans Zipkin 端点。使用你的 IP 地址更新。

❷ 将采样率配置为 1 以追踪每个请求。

创建一个将追踪通过该路由的请求的示例路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "zipkin-tracing-route",
  "uri": "/anything",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org": 1
    }
  }
}'

将 zipkin 配置为全局插件，并创建一个将追踪通过该路由的请求的示例路由：

adc-route.yaml
global_rules:
  zipkin:
    // Annotate 1
    endpoint: "http://192.168.42.145:9411/api/v2/spans"
    // Annotate 2
    sample_ratio: 1
services:
  - name: httpbin Service
    routes:
      - uris:
          - /anything
        name: zipkin-tracing-route
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          weight: 1

❶ 设置为 /spans Zipkin 端点。

❷ 将采样率配置为 1 以追踪每个请求。

将配置同步到 APISIX：

adc sync -f adc-route.yaml

Gateway API
APISIX CRD

更新你的 GatewayProxy 清单以将 zipkin 启用为全局插件：

提示

要在添加其他配置之前查看当前 GatewayProxy 配置，请运行：

kubectl get gatewayproxy apisix-config -o yaml

gateway-proxy.yaml
apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: ingress-apisix
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      auth:
        adminKey:
          value: edd1c9f034335f136f87ad84b625c8f1
        type: AdminKey
      service:
        name: apisix-admin
        port: 9180
  plugins:
  - name: zipkin
    enabled: true
    config:
      // Annotate 1
      endpoint: http://zipkin:9411/api/v2/spans
      // Annotate 2
      sample_ratio: 1

❶ 设置为 /spans Zipkin 端点。

❷ 将采样率配置为 1 以追踪每个请求。

为你要收集追踪的示例路由创建另一个 Kubernetes 清单文件：

httpbin-route.yaml
apiVersion: v1
kind: Service
metadata:
  namespace: ingress-apisix
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: ingress-apisix
  name: zipkin-tracing-route
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /anything
    backendRefs:
    - name: httpbin-external-domain
      port: 80

将配置应用到你的集群：

kubectl apply -f gateway-proxy.yaml -f httpbin-route.yaml

创建一个 Kubernetes 清单文件以全局启用 zipkin：

global-zipkin.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixGlobalRule
metadata:
  namespace: ingress-apisix
  name: global-zipkin
spec:
  ingressClassName: apisix
  plugins:
    - name: zipkin
      enable: true
      config:
        config:
        // Annotate 1
        endpoint: http://zipkin:9411/api/v2/spans
        // Annotate 2
        sample_ratio: 1

❶ 设置为 /spans Zipkin 端点。

❷ 将采样率配置为 1 以追踪每个请求。

为你要收集追踪的示例路由创建另一个 Kubernetes 清单文件：

httpbin-route.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: ingress-apisix
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: zipkin-tracing-route
spec:
  ingressClassName: apisix
  http:
    - name: zipkin-tracing-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain

将配置应用到你的集群：

kubectl apply -f global-zipkin.yaml -f httpbin-route.yaml

追踪请求

向路由发送请求：

curl "http://127.0.0.1:9080/anything"

你应该收到类似以下的 HTTP/1.1 200 OK 响应，并在标头中包含追踪信息：

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "127.0.0.1", 
    "User-Agent": "curl/7.64.1", 
    "X-Amzn-Trace-Id": "Root=1-65b1dd40-339dc8832b4b78d36703cbc0", 
    "X-B3-Parentspanid": "6ca01ad46bdb0198", 
    "X-B3-Sampled": "1", 
    "X-B3-Spanid": "f02ab1a9b2d5c3e4", 
    "X-B3-Traceid": "ef5b16781c7ad00ea2e3efa6f784031a", 
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  ...
}

导航到 http://127.0.0.1:9411/zipkin 上的 Zipkin Web UI，然后单击 Run Query，你应该会看到与请求对应的追踪：

来自请求的追踪

单击 Show 以查看更多追踪详细信息：

v2 追踪跨度

默认情况下，该插件使用 span 版本 2，其中每个追踪请求都有 proxy 和 response span。更具体地说：

proxy 表示从请求开始到 header_filter 开始的时间
response 表示从 header_filter 开始到 log 开始的时间

要了解不同 span 版本之间的差异，请参阅插件文档。

下一步

你现在已经将 Zipkin 与 APISIX 集成以进行追踪。除了将追踪发送到 Zipkin 之外，zipkin 插件还可以将追踪发送到 Jaeger 和其他兼容的收集器。有关更多详细信息，请参阅 zipkin 插件文档。

前置条件​

启动 Zipkin 实例​

配置 APISIX​

追踪请求​

下一步​

前置条件

启动 Zipkin 实例

配置 APISIX

追踪请求

下一步