Managed Service for OpenTelemetry:Usar OpenTelemetry para analisar rastreamento no NGINX

Para habilitar a análise de rastreamento no NGINX, carregue o ngx_otel_module e configure seus parâmetros no arquivo de configuração principal /etc/nginx/nginx.conf do NGINX. Para mais informações sobre os parâmetros do ngx_otel_module, consulte a documentação oficial do ngx_otel_module.

• Ative a análise de rastreamento para todas as requisições HTTP

  ngx_otel_module V0.1.2 or later

  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 or earlier

  Nota

  Substitua as seguintes variáveis na configuração:

  • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}: O endpoint gRPC do OpenTelemetry Collector implantado, por exemplo, localhost:4317. Este endpoint difere daquele obtido nos pré-requisitos do Managed Service for OpenTelemetry.

  • ${SERVICE_NAME}: O nome da aplicação. Este nome aparece como o nome da aplicação NGINX no console do 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.
      ...
  }

• Habilite a análise de rastreamento para requisições HTTP enviadas a uma única localização

  ngx_otel_module V0.1.2 or later

  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 or earlier

  Nota

  Substitua as duas variáveis na configuração:

  • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT}: O endpoint gRPC do OpenTelemetry Collector implantado, por exemplo, localhost:4317. Este endpoint difere daquele obtido nos pré-requisitos do Managed Service for OpenTelemetry.

  • ${SERVICE_NAME}: O nome da aplicação. Este nome aparece como o nome da aplicação NGINX no console do 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.
  
              ...
          }
      }
  }

Etapa 3: (Opcional) Implantar um OpenTelemetry Collector

Etapa 4: Visualize rastros do NGINX

Após concluir as etapas anteriores e reiniciar o NGINX, envie requisições ao NGINX para gerar rastros. Em seguida, faça login no console do Managed Service for OpenTelemetry para visualizar os rastros do NGINX gerados pelo OpenTelemetry.

• Na página Applications, localize a aplicação NGINX e clique no nome dela.

• Na aba Trace details, visualize os detalhes do rastro, incluindo duração da requisição, endereço IP do cliente e código de status HTTP. Se o service de backend também estiver conectado ao Managed Service for OpenTelemetry, os rastros do NGINX e dos services de backend serão associados automaticamente para fornecer uma visão integrada. Na página Trace details, o gráfico em cascata de spans mostra o rastro completo de uma requisição que passa pelo nginx e pelo service de backend Node.js (ot-node-demo). O nginx recebe primeiro a requisição /hello (duração total de 6 ms, HTTP 200) e depois a encaminha para GET /hello no ot-node-demo (5,76 ms), que contém três spans internos: middleware-query, middleware-expressInit e request handler-/hello. O painel Span details à direita exibe os atributos da aplicação nginx, incluindo http.status_code=200, http.route=/hello e http.user_agent=curl/7.61.1.

Etapa 1: Preparar o ambiente

• Instale Git, docker e docker Compose.

• Obter o endpoint.

Etapa 2: Crie diretórios do projeto

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

Crie os diretórios.

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

mkdir -p nginx_conf otel_conf backend

Etapa 3: Crie os arquivos de configuração do NGINX

1. Crie o arquivo de configuração principal nginx.conf do NGINX.

   ngx_otel_module V0.1.2 or later

   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 or earlier

   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. Crie o arquivo de configuração default.conf do 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

Etapa 4: (Opcional) Crie o arquivo de configuração do OpenTelemetry Collector

Crie o arquivo de configuração do OpenTelemetry Collector. Este arquivo define os métodos para receber, processar e reportar dados.

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

Etapa 5: Crie um service de backend usando Node.js

1. Crie o arquivo package.json. Ele contém as informações de configuração do service de backend, incluindo nome, versão e dependências.

   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. Crie o arquivo main.js, que define uma aplicação web básica em 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. Crie o Dockerfile.

   ngx_otel_module V0.1.2 or later

   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 or earlier

   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

Etapa 6: Crie o arquivo de configuração do docker Compose

O arquivo de configuração do docker Compose define as configurações de uma aplicação multi-container, incluindo o NGINX atuando como proxy reverso, o OpenTelemetry Collector e um service de backend em Node.js. Este arquivo também estabelece as conexões de rede e mapeamentos de portas entre os 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

Etapa 7: Iniciar o service

1. Execute o seguinte comando no diretório nginx-otel-demo:

   docker compose up -d

   Saída esperada:

   ngx_otel_module V0.1.2 or later

   [+] 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 or earlier

   [+] 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. Acesse o service de backend.

   curl http://localhost:80/hello

   Saída esperada:

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

3. Faça login no console do Managed Service for OpenTelemetry para visualizar os rastros do NGINX e do service de backend.

   Neste exemplo, nginx aparece como o nome da aplicação NGINX na página Applications, e o nome do service de backend é ot-nodejs-demo.