使用OpenTelemetry对Kong网关进行链路追踪

一、为Kong开启链路追踪

方法一：在环境变量里设置

• KONG_TRACING_INSTRUMENTATIONS：开启链路追踪。

• KONG_TRACING_SAMPLING_RATE：采样率，取值范围为0到1.0。1.0为全部采样，0为不采样。

KONG_TRACING_INSTRUMENTATIONS=all
KONG_TRACING_SAMPLING_RATE=1

方法二：在kong.conf配置文件中设置

• tracing_instrumentations：开启链路追踪。

• tracing_sampling_rate：采样率，取值范围为0到1.0。1.0为全部采样，0为不采样。

# kong.conf  
tracing_instrumentations = all  
tracing_sampling_rate = 1.0  
...

二、配置OpenTelemetry上报参数

方法一：在kong.yaml中设置OpenTelemetry上报地址和应用名称

# kong.yaml
...
plugins:
  ...
  - name: opentelemetry
    config:
      traces_endpoint: ${HTTP_ENDPOINT}
      resource_attributes:
        service.name: ${SERVICE_NAME}

方法二：通过Kong Admin API设置OpenTelemetry上报地址和应用名称

curl -X POST http://localhost:8001/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
  "name": "opentelemetry",
  "config": {
    "traces_endpoint": "${HTTP_ENDPOINT}",
    "resource_attributes": {
      "service.name": "${SERVICE_NAME}"
    }
  }
}
    '

方法三：在Kubernetes中创建KongClusterPlugin资源，并设置OpenTelemetry上报地址和应用名称

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
 name: <global-opentelemetry>
 annotations:
   kubernetes.io/ingress.class: kong
 labels:
   global: "true"
config:
 traces_endpoint: ${HTTP_ENDPOINT}
 resource_attributes:
   service.name: ${SERVICE_NAME}
plugin: opentelemetry

三、查看Kong调用链

完成以上配置后，您可通过Kong创建路由并进行访问，以生成调用链。然后登录可观测链路 OpenTelemetry 版控制台，查看由OpenTelemetry生成的Kong调用链。

• 在应用列表页面查看Kong应用。

• 在调用链分析页面打开Kong的调用链，查看请求耗时、客户端IP、 HTTP状态码、HTTP路由等信息。

四、高级配置（可选）

# kong.yaml
...
plugins:
  ...
  - name: opentelemetry
    config:
      ...
      propagation:
        extract: [ w3c, b3, jaeger, ot ]
        inject: [ preserve ]
        default_format: "w3c"

操作步骤

1. 下载Kong/docker-kong开源项目。

   git clone https://github.com/Kong/docker-kong.git && cd docker-kong/compose

2. 创建后端服务（以Node.js应用为例）。

   本步骤会创建一个使用Express框架的Node.js应用，该应用在7001端口启动并暴露/hello端点。

   1. 创建应用目录。

      mkdir backend && cd backend

   2. 创建package.json。

      cat << EOF > package.json
      {
        "name": "backend",
        "version": "1.0.0",
        "main": "index.js",
        "scripts": {},
        "keywords": [],
        "author": "",
        "license": "ISC",
        "description": "",
        "dependencies": {
          "@opentelemetry/api": "^1.9.0",
          "@opentelemetry/auto-instrumentations-node": "^0.52.0",
          "axios": "^1.7.7",
          "express": "^4.21.1"
        }
      }
      EOF

   3. 创建main.js。

      cat << EOF > main.js
      "use strict";
      const axios = require("axios").default;
      const express = require("express");
      const app = express();
      app.get("/", async (req, res) => {
        const result = await axios.get("http://localhost:7001/hello");
        return res.status(201).send(result.data);
      });
      app.get("/hello", async (req, res) => {
        console.log("hello world!")
        res.json({ code: 200, msg: "success" });
      });
      app.use(express.json());
      app.listen(7001, () => {
        console.log("Listening on http://localhost:7001");
      });
      EOF

   4. 创建Dockerfile。

      说明

      请按照前提条件中的步骤获取HTTP接入点，并替换${HTTP_ENDPOINT}。

      cat << EOF > Dockerfile
      FROM node:20.16.0
      WORKDIR /app
      COPY package*.json ./
      RUN npm install
      COPY . .
      ENV OTEL_TRACES_EXPORTER="otlp"
      ENV OTEL_LOGS_EXPORTER=none
      ENV OTEL_METRICS_EXPORTER=none
      ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="${HTTP_ENDPOINT}"
      ENV OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
      ENV OTEL_SERVICE_NAME="ot-nodejs-demo"
      ENV NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
      EXPOSE 7001
      CMD ["node", "main.js"]
      EOF

3. 为Kong开启链路追踪，并将后端服务添加到Docker Compose中。

   1. 从backend目录回到上层目录。

      cd ..

   2. 修改docker compose。

      vim docker-compose.yml

   3. 在docker-compose.yml文件中为Kong添加环境变量，开启链路追踪。

      ...
      services:
        kong:
          ...
          environment:
            ...
            # 新增两个环境变量
            KONG_TRACING_INSTRUMENTATIONS: all
            KONG_TRACING_SAMPLING_RATE: 1.0
          ...
      ...

   4. 在docker-compose.yml文件中定义名为backend-api的Nodejs后端服务。

      ...
      services:
        ...
        backend-api:
          build:
            context: ./backend
            dockerfile: Dockerfile
          environment:
            NODE_ENV: production
          ports:
            - "7001:7001"
          networks:
            - kong-net
      ...

4. 在Kong中配置后端服务和路由规则，并启用OpenTelemetry插件。

   1. 进入conf文件夹。

      cd config

   2. 将以下内容追加到kong.yaml中。

      说明

      请按照前提条件中的步骤获取HTTP接入点，并替换${HTTP_ENDPOINT}。

      cat << EOF >> kong.yaml
      
      services:
        - name: backend-api
          url: http://backend-api:7001
          routes:
            - name: main-route
              paths:
                - /hello
      
      plugins:
        - name: opentelemetry
          config:
            traces_endpoint: ${HTTP_ENDPOINT} # 请替换为实际的HTTP接入点
            headers:
              X-Auth-Token: secret-token
            resource_attributes:
              service.name: kong-dev
      EOF

5. 启动Kong和后端服务。

   1. 回到上层目录。

      cd ..

   2. 在docker-compose.yml文件所在目录中执行命令，启动Kong和后端服务。

      docker compose up -d

6. 通过Kong访问后端服务。

   curl http://localhost:8000/hello
   
   # 预期输出：{"code":200,"msg":"success"}

7. 前往可观测链路 OpenTelemetry 版控制台，查看Kong及后端服务的调用链。

   说明

   在本例中，Kong在应用列表页面的名称显示为kong-dev，后端应用名称为ot-nodejs-demo。