Managed Service for OpenTelemetry:Use OpenTelemetry to report the trace data of Kong Gateway

Step 1: Enable tracing for Kong Gateway

Method 1: Enable tracing by using environment variables

• KONG_TRACING_INSTRUMENTATIONS: enables tracing.

• KONG_TRACING_SAMPLING_RATE: the sampling rate. Valid values: 0 to 1.0. A value of 1.0 indicates that all the data is sampled. A value of 0 indicates that no data is sampled.

KONG_TRACING_INSTRUMENTATIONS=all
KONG_TRACING_SAMPLING_RATE=1

Method 2: Enable tracing in the kong.conf file

• tracing_instrumentations: enables tracing.

• tracing_sampling_rate: the sampling rate. Valid values: 0 to 1.0. A value of 1.0 indicates that all the data is sampled. A value of 0 indicates that no data is sampled.

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

Step 2: Configure the parameters for reporting data by using OpenTelemetry

For information about configuring OpenTelemetry reporting parameters, see OpenTelemetry.

Method 1: Configure the OpenTelemetry endpoint and application name in the kong.yaml configuration file

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

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

Method 2: Use the Kong Admin API to configure the OpenTelemetry endpoint and application name

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

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

Method 3: Create a KongClusterPlugin resource in the Kubernetes cluster and configure the OpenTelemetry endpoint and application name

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

Step 3: View the trace data of Kong Gateway

After you complete the preceding configurations, you can create routes in Kong Gateway and use Kong Gateway to access backend services to generate traces. Then, you can log on to the Managed Service for OpenTelemetry console to view the traces generated by Managed Service for OpenTelemetry for Kong Gateweay.

• On the Applications page, view the Kong Gateway application.

• On the Trace Explorer page, open a trace of Kong Gateway and view information such as the request duration, client IP address, HTTP status code, and HTTP route.

Step 4: (Optional) Configure advanced settings

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

Procedure

1. Download the Kong/docker-kong open source project.

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

2. Create a backend service. In this example, a Node.js application is created.

   This step creates a Node.js application that uses the Express framework. This application is started on port 7001 and exposes the /hello endpoint.

   1. Create an application directory.

      mkdir backend && cd backend

   2. Create the package.json file.

      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. Create the main.js file.

      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. Create the Dockerfile.

      Note

      Replace ${HTTP_ENDPOINT} with the HTTP endpoint that you obtained in the Prerequisites section.

      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. Enable tracing for Kong Gateway and add the backend service to Docker Compose.

   1. Return from the backend directory to the upper-level directory.

      cd ..

   2. Modify the configuration file of Docker Compose.

      vim docker-compose.yml

   3. Add environment variables to the docker-compose.yml file to enable tracing for Kong Gateway.

      ...
      services:
        kong:
          ...
          environment:
            ...
            # Add two environment variables.
            KONG_TRACING_INSTRUMENTATIONS: all
            KONG_TRACING_SAMPLING_RATE: 1.0
          ...
      ...

   4. Define a Node.js backend service named backend-api in the docker-compose.yml file.

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

4. Configure the backend service and routing rules in Kong Gateway, and enable the OpenTelemetry plug-in.

   1. Go to the config directory.

      cd config

   2. Add the following content to the kong.yaml file:

      Note

      Replace ${HTTP_ENDPOINT} with the HTTP endpoint that you obtained in the Prerequisites section.

      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} # Replace ${HTTP_ENDPOINT} with the obtained HTTP endpoint.
            headers:
              X-Auth-Token: secret-token
            resource_attributes:
              service.name: kong-dev
      EOF

5. Start Kong Gateway and the backend service.

   1. Return to the upper-level directory.

      cd ..

   2. Run the following command in the directory in which the docker-compose.yml file resides to start Kong Gateway and the backend service:

      docker compose up -d

6. Access the backend service by using Kong Gateway.

   curl http://localhost:8000/hello
   
   # Expected output: {"code":200,"msg":"success"}

7. Log on to the Managed Service for OpenTelemetry console to view the traces of Kong Gateway and the backend service.

   Note

   In this example, the name of Kong Gateway displayed on the Applications page is kong-dev, and the name of the backend service is ot-nodejs-demo.