Managed Service for OpenTelemetry:Usar OpenTelemetry para realizar análisis de trazas en NGINX

Para habilitar la función de análisis de trazas en NGINX, cargue el módulo ngx_otel_module y configure sus parámetros en el archivo de configuración principal /etc/nginx/nginx.conf de NGINX. Para obtener más información sobre los parámetros del módulo ngx_otel_module, consulte la documentación oficial de ngx_otel_module.

• Habilitar el análisis de trazas para todas las solicitudes HTTP

  ngx_otel_module V0.1.2 o posterior

  load_module modules/ngx_otel_module.so; # Load ngx_otel_module
  ...
  http {
      ...
  
      otel_exporter {
          endpoint "${GRPC_ENDPOINT}"; # The gRPC endpoint obtained in the prerequisites.
          header Authentication "${GRPC_TOKEN}"; # The authentication token obtained in the prerequisites.
      }
  
      otel_trace on;                     # Enable Tracing Analysis.
      otel_service_name ${SERVICE_NAME};  # The application name.
      otel_trace_context propagate;         # Inject the trace context into downstream services.
      ...
  }

  ngx_otel_module V0.1.1 o anterior

  Nota

  Reemplace las siguientes variables en la configuración:

  • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}: el endpoint de gRPC del OpenTelemetry Collector que desplegó, por ejemplo, localhost:4317. Este endpoint es distinto del endpoint de Managed Service for OpenTelemetry obtenido en los requisitos previos.

  • ${SERVICE_NAME}: el nombre de la aplicación. Este nombre se muestra como el nombre de la aplicación NGINX en la consola de Managed Service for OpenTelemetry.

  load_module modules/ngx_otel_module.so; # Load the ngx_otel_module.
  ...
  http {
      ...
  
      otel_exporter {
          endpoint ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}; # The reporting address of the OpenTelemetry Collector, such as localhost:4317.
      }
  
      otel_trace on;                     # Enable Tracing Analysis.
      otel_service_name ${SERVICE_NAME};  # The application name.
      otel_trace_context propagate;         # Inject the trace context into downstream services.
      ...
  }

• Habilitar el análisis de trazas para las solicitudes HTTP enviadas a una sola ubicación

  ngx_otel_module V0.1.2 o posterior

  load_module modules/ngx_otel_module.so; # Load the ngx_otel_module.
  
  ...
  
  http {
  
      otel_exporter {
          endpoint "${GRPC_ENDPOINT}"; # The gRPC endpoint obtained in the prerequisites.
          header Authentication "${GRPC_TOKEN}"; # The authentication token obtained in the prerequisites.
      }
  
      server {
          listen 127.0.0.1:80;
  
          location /hello {
              otel_trace         on;             # Enable Tracing Analysis only for 127.0.0.1:80/hello.
              otel_service_name ${SERVICE_NAME}  # The application name.
              otel_trace_context propagate;         # Inject the trace context into downstream services.
  
              ...
          }
      }
  }

  ngx_otel_module V0.1.1 o anterior

  Nota

  Reemplace las dos variables en la configuración:

  • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}: el endpoint de gRPC del OpenTelemetry Collector que desplegó, por ejemplo, localhost:4317. Este endpoint es distinto del endpoint de Managed Service for OpenTelemetry obtenido en los requisitos previos.

  • ${SERVICE_NAME}: el nombre de la aplicación. Este nombre se muestra como el nombre de la aplicación NGINX en la consola de Managed Service for OpenTelemetry.

  load_module modules/ngx_otel_module.so; # Load the ngx_otel_module.
  
  ...
  
  http {
  
      otel_exporter {
          endpoint ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}; # The reporting address of the OpenTelemetry Collector, for example, localhost:4317.
      }
  
      server {
          listen 127.0.0.1:80;
  
          location /hello {
              otel_trace         on;             # Enable Tracing Analysis only for 127.0.0.1:80/hello.
              otel_service_name ${SERVICE_NAME}  # The application name.
              otel_trace_context propagate;         # Inject the trace context into downstream services.
  
              ...
          }
      }
  }

Paso 3: (Opcional) Desplegar un OpenTelemetry Collector

Paso 4: Consultar las trazas de NGINX

Después de completar los pasos anteriores y reiniciar NGINX, envíe solicitudes a NGINX para generar trazas. Luego, inicie sesión en la consola de Managed Service for OpenTelemetry para consultar las trazas de NGINX generadas por OpenTelemetry.

• En la página Applications, busque la aplicación NGINX y haga clic en su nombre.

• En la pestaña Trace details, consulte los detalles de la traza, como la duración de la solicitud, la dirección IP del cliente y el código de estado HTTP. Si su servicio de backend también está conectado a Managed Service for OpenTelemetry, las trazas de NGINX y de los servicios de backend se asocian automáticamente para ofrecer una vista integrada. En la página Trace details, la cascada de spans muestra la traza completa de una solicitud que pasa por nginx y por el servicio de backend de Node.js (ot-node-demo). Primero, nginx recibe la solicitud /hello (duración total de 6 ms, HTTP 200) y luego la reenvía a GET /hello en ot-node-demo (5.76 ms), que contiene tres spans internos: middleware-query, middleware-expressInit y request handler-/hello. El panel Span details, ubicado a la derecha, muestra los atributos de la aplicación nginx, entre ellos http.status_code=200, http.route=/hello y http.user_agent=curl/7.61.1.

Paso 1: Preparar el entorno

• Instale Git, Docker y Docker Compose.

• Obtain the endpoint.

Paso 2: Crear los directorios del proyecto

nginx-otel-demo
│
├── docker-compose.yml          # The configuration file of Docker Compose.
│
├── nginx_conf/                 # The configuration files of NGINX.
│   ├── default.conf
│   └── nginx.conf              
│
├── otel_conf/                  # The configuration file of the OpenTelemetry Collector.
│   └── config.yaml           
│
└── backend/                    # The backend service developed by using Node.js.
    ├── Dockerfile              
    ├── main.js
    ├── package.json
    └── package-lock.json

Cree los directorios.

mkdir nginx-otel-demo && cd nginx-otel-demo

mkdir -p nginx_conf otel_conf backend

Paso 3: Crear los archivos de configuración de NGINX

1. Cree el archivo de configuración principal nginx.conf de NGINX.

   ngx_otel_module V0.1.2 o posterior

   cat << 'EOF' > nginx_conf/nginx.conf
   load_module modules/ngx_otel_module.so;
   
   user  nginx;
   worker_processes  auto;
   
   error_log  /var/log/nginx/error.log notice;
   pid        /var/run/nginx.pid;
   
   events {
       worker_connections  1024;
   }
   
   http {
       include       /etc/nginx/mime.types;
       default_type  application/octet-stream;
   
       log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                         '$status $body_bytes_sent "$http_referer" '
                         '"$http_user_agent" "$http_x_forwarded_for"';
   
       access_log  /var/log/nginx/access.log  main;
   
       sendfile        on;
       #tcp_nopush     on;
   
       keepalive_timeout  65;
   
       #gzip  on;
   
       otel_exporter {
           endpoint "${GRPC_ENDPOINT}";
           header Authentication "${GRPC_TOKEN}";
       }
   
       otel_trace on;
   
       otel_trace_context propagate;
   
       otel_service_name nginx;
   
       include /etc/nginx/conf.d/*.conf;
   
   }
   EOF

   ngx_otel_module V0.1.1 o anterior

   load_module modules/ngx_otel_module.so;
   
   user  nginx;
   worker_processes  auto;
   
   error_log  /var/log/nginx/error.log notice;
   pid        /var/run/nginx.pid;
   
   events {
       worker_connections  1024;
   }
   
   http {
       include       /etc/nginx/mime.types;
       default_type  application/octet-stream;
   
       log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                         '$status $body_bytes_sent "$http_referer" '
                         '"$http_user_agent" "$http_x_forwarded_for"';
   
       access_log  /var/log/nginx/access.log  main;
   
       sendfile        on;
       #tcp_nopush     on;
   
       keepalive_timeout  65;
   
       #gzip  on;
   
       otel_exporter {
           endpoint otel-collector:4317;
       }
   
       otel_trace on;
   
       otel_trace_context propagate;
   
       otel_service_name nginx;
   
       include /etc/nginx/conf.d/*.conf;
   
   }
   EOF
   

2. Cree el archivo de configuración default.conf de NGINX.

   cat << 'EOF' > nginx_conf/default.conf
   server {
       listen       80;
       server_name  localhost;
   
       location / {
           root   /usr/share/nginx/html;
           index  index.html index.htm;
       }
       
       # Configure parameters.
       location /hello {
           proxy_pass http://backend-api:7001/hello;
           proxy_http_version 1.1;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   
       # redirect server error pages to the static page /50x.html
       #
       error_page   500 502 503 504  /50x.html;
       location = /50x.html {
           root   /usr/share/nginx/html;
       }
   }
   EOF

Paso 4: (Opcional) Crear el archivo de configuración del OpenTelemetry Collector

Cree el archivo de configuración del OpenTelemetry Collector. Este archivo define los métodos para recibir, procesar y reportar datos.

cat << 'EOF' > otel_conf/config.yaml
receivers:
  otlp:
    protocols:
      grpc: 
        endpoint: 0.0.0.0:4317

exporters:
  otlp:
    endpoint: ${GRPC_ENDPOINT}
    tls:
      insecure: true
    headers:
      "Authentication": "${GRPC_ENDPOINT_TOKEN}"

processors:
  batch:
  
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
EOF

Paso 5: Crear un servicio de backend con Node.js

1. Cree el archivo package.json. Este archivo contiene la información de configuración del servicio de backend, incluido el nombre del servicio, la versión del servicio y las dependencias.

   cat << 'EOF' > backend/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

2. Cree el archivo main.js que define una aplicación web básica de Express.

   cat << 'EOF' > backend/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

3. Cree el Dockerfile.

   ngx_otel_module V0.1.2 o posterior

   cat << 'EOF' > backend/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_PROTOCOL=grpc
   ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="${GRPC_ENDPOINT}"
     export OTEL_EXPORTER_OTLP_HEADERS=Authentication=${GRPC_TOKEN}
   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

   ngx_otel_module V0.1.1 o anterior

   cat << 'EOF' > backend/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_PROTOCOL=grpc
   ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://otel-collector:4317"
   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

Paso 6: Crear el archivo de configuración de Docker Compose

El archivo de configuración de Docker Compose define los ajustes de una aplicación de múltiples contenedores, incluidos NGINX como proxy inverso, el OpenTelemetry Collector y un servicio de backend de Node.js. También establece las conexiones de red y las asignaciones de puertos entre los componentes.

cat << 'EOF' > docker-compose.yml
version: "3"

services:
  nginx:
    image: nginx:1.27.5-alpine-otel # The default NGINX image that contains the ngx_otel_module V0.1.2.
    volumes:
      - ./nginx_conf/nginx.conf:/etc/nginx/nginx.conf:ro 
      - ./nginx_conf/default.conf:/etc/nginx/conf.d/default.conf:ro 
    ports:
      - "80:80"
    networks:
      - nginx-otel-demo

  backend-api:
    build:
      context: ./backend
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
    ports:
      - "7001:7001"
    networks:
      - nginx-otel-demo

networks:
  nginx-otel-demo:
    driver: bridge
EOF

cat << 'EOF' > docker-compose.yml
version: "3"

services:
  nginx:
    image: nginx:1.27.2-alpine-otel # The default NGINX image that contains the OpenTelemetry module.
    volumes:
      - ./nginx_conf/nginx.conf:/etc/nginx/nginx.conf:ro 
      - ./nginx_conf/default.conf:/etc/nginx/conf.d/default.conf:ro 
    ports:
      - "80:80"
    networks:
      - nginx-otel-demo

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    volumes:
      - ./otel_conf/config.yaml:/etc/otelcol-contrib/config.yaml # Mount the configuration file for the OpenTelemetry Collector.
    ports:
      - "4317:4317" # OTLP gRPC receiver
    networks:
      - nginx-otel-demo

  backend-api:
    build:
      context: ./backend
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
    ports:
      - "7001:7001"
    networks:
      - nginx-otel-demo

networks:
  nginx-otel-demo:
    driver: bridge
EOF

Paso 7: Iniciar el servicio

1. Ejecute el siguiente comando en el directorio nginx-otel-demo:

   docker compose up -d

   Resultado esperado:

   ngx_otel_module V0.1.2 o posterior

   [+] Running 4/4
    ✔ Network nginx-otel-demo_nginx-otel-demo       Created
    ✔ Container nginx-otel-demo-nginx-1             Started
    ✔ Container nginx-otel-demo-backend-api-1        Started

   ngx_otel_module V0.1.1 o anterior

   [+] Running 4/4
    ✔ Network nginx-otel-demo_nginx-otel-demo       Created
    ✔ Container nginx-otel-demo-nginx-1              Started
    ✔ Container nginx-otel-demo-backend-api-1         Started
    ✔ Container nginx-otel-demo-otel-collector-1      Started

2. Acceda al servicio de backend.

   curl http://localhost:80/hello

   Resultado esperado:

   {"code":200,"msg":"success"}

3. Inicie sesión en la consola de Managed Service for OpenTelemetry para consultar las trazas de NGINX y del servicio de backend.

   En este ejemplo, nginx se muestra como el nombre de la aplicación NGINX en la página Applications, mientras que el nombre del servicio de backend es ot-nodejs-demo.