Tous les produits
Search

Ce produit

    Managed Service for OpenTelemetry:Utiliser OpenTelemetry pour analyser les traces sur NGINX

    Centre de documentation

    Managed Service for OpenTelemetry:Utiliser OpenTelemetry pour analyser les traces sur NGINX

    Dernière mise à jour :Aug 11, 2026

    Cette rubrique explique comment utiliser OpenTelemetry pour analyser les traces sur NGINX. NGINX est un serveur web et un proxy inverse open source, léger et performant, dont les fonctionnalités sont extensible via des modules. Le module ngx_otel_module collecte les traces de NGINX et les transfère vers le service Managed Service for OpenTelemetry.

    Limitations

    • Le module ngx_otel_module transmet les données de trace de NGINX uniquement via gRPC. La transmission via HTTP n'est pas prise en charge.

    • Notes de version du module ngx_otel_module :

      • V0.1.2 ou version ultérieure : vous pouvez transférer directement les traces NGINX vers le service Managed Service for OpenTelemetry.

      • V0.1.1 ou version antérieure : le module ngx_otel_module ne prend pas en charge la configuration des jetons d'authentification gRPC. Vous devez donc déployer un collecteur OpenTelemetry pour acheminer les traces NGINX vers le service Managed Service for OpenTelemetry.

    Prérequis

    Obtenir un endpoint gRPC et un jeton d'authentification

    New console

    1. Connectez-vous à la console Managed Service for OpenTelemetry. Dans le volet de navigation de gauche, cliquez sur Integration Center.

    2. Sur la page Integration Center, cliquez sur la carte OpenTelemetry dans la section Open Source Frameworks.

    3. Dans le panneau OpenTelemetry, cliquez sur l'onglet Start Integration, puis sélectionnez la région dans laquelle vous souhaitez envoyer les données de trace.

      Remarque

      Les ressources sont initialisées automatiquement dans la région à laquelle vous accédez pour la première fois.

    4. Configurez les paramètres Connection Type et Export Protocol, puis copiez un endpoint.

      • Connection Type : si votre service est déployé sur Alibaba Cloud et réside dans la région que vous avez sélectionnée, nous vous recommandons de définir ce paramètre sur Alibaba Cloud VPC Network. Sinon, définissez-le sur Public Network.

      • Export Protocol : définissez ce paramètre sur gRPC, en fonction du protocole pris en charge par le client.

      87.jpg

    Old console

    1. Connectez-vous à la console Managed Service for OpenTelemetry.

    2. Dans le volet de navigation de gauche, cliquez sur Cluster Configurations. Sur la page qui s'affiche, cliquez sur l'onglet Access point information.

    3. Dans la barre de navigation supérieure, sélectionnez la région dans laquelle vous souhaitez envoyer les données de trace. Dans la section Cluster Information, activez l'option Show Token.

    4. Définissez le paramètre Client sur OpenTelemetry.

      Dans la colonne Related Information du tableau, copiez un endpoint dans la section Report data through gRPC.86.jpg

      Remarque

      Si votre application est déployée dans un environnement de production Alibaba Cloud, utilisez un endpoint VPC (Virtual Private Cloud). Sinon, utilisez un endpoint public.

    Procédure

    Étape 1 : Télécharger le module ngx_otel_module

    Method 1: Use the package manager

    • Téléchargez le module ngx_otel_module pour Alibaba Cloud Linux, Red Hat Linux, Red Hat Enterprise Linux ou leurs dérivés :

      sudo yum install nginx-module-otel

    • Téléchargez le module ngx_otel_module pour Debian, Ubuntu ou leurs dérivés :

      sudo apt install nginx-module-otel

    Method 2: Use the pre-built Docker image

    Remarque

    NGINX V1.27.5 et versions ultérieures utilisent par défaut le module ngx_otel_module V0.1.2.

    Accédez au site officiel de Docker, recherchez et récupérez les images NGINX suffixées par -otel, telles que nginx:1.23.3-otel, puis déployez le service en suivant la procédure standard de démarrage d'un conteneur Docker.

    image

    Étape 2 : Activer le module ngx_otel_module

    Pour activer l'analyse de traçage pour NGINX, chargez le module ngx_otel_module et configurez ses paramètres dans le fichier de configuration principal /etc/nginx/nginx.conf de NGINX. Pour plus d'informations sur les paramètres du module ngx_otel_module, consultez la documentation officielle du module ngx_otel_module.

    • Activer l'analyse de traçage pour toutes les requêtes 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

      Remarque

      Remplacez les variables suivantes dans la configuration :

      • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT} : endpoint gRPC du collecteur OpenTelemetry que vous avez déployé, par exemple localhost:4317. Cet endpoint diffère de celui du service Managed Service for OpenTelemetry obtenu dans les prérequis.

      • ${SERVICE_NAME} : nom de l'application. Ce nom s'affiche comme nom d'application NGINX dans la console 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.
    ...
}

    • Activer l'analyse de traçage pour les requêtes HTTP envoyées à un emplacement unique

      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

      Remarque

      Remplacez les deux variables dans la configuration :

      • ${OTEL_COLLECTOR_GRPC_RECEIVER_ENDPOINT} : endpoint gRPC du collecteur OpenTelemetry que vous avez déployé, par exemple localhost:4317. Cet endpoint diffère de celui du service Managed Service for OpenTelemetry obtenu dans les prérequis.

      • ${SERVICE_NAME} : nom de l'application. Ce nom s'affiche comme nom d'application NGINX dans la console 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.

            ...
        }
    }
}

    Étape 3 : (Facultatif) Déployer un collecteur OpenTelemetry

    Remarque

    Cette étape est requise uniquement pour le module ngx_otel_module V0.1.1 ou une version antérieure.

    Method 1: Installation in the ACK console

    1. Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Marketplace > Marketplace.

    2. Sur la page qui s'affiche, recherchez et cliquez sur opentelemetry-collector. Dans le panneau qui s'ouvre, cliquez sur Deploy en haut à droite.

    3. Dans le panneau Deploy, sélectionnez le cluster cible et cliquez sur Next.

    4. À l'étape Parameters, ajoutez les paramètres suivants et cliquez sur OK.

      Remarque

      Remplacez ${GRPC_ENDPOINT} et ${GRPC_ENDPOINT_TOKEN} par l'endpoint gPRC et le jeton d'authentification récupérés dans la section Prérequis.

      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]

      Exemple :

      81

    Method 2: Manual installation

    L'exemple suivant montre comment déployer le collecteur OpenTelemetry à l'aide de Docker. Pour plus d'informations, consultez la page Install the Collector.

    1. Créez un fichier nommé opentelemetry-config.yaml et copiez-y le contenu suivant.

      Ce fichier sert à définir et configurer les comportements et fonctionnalités du collecteur OpenTelemetry, y compris les méthodes de réception, de traitement et d'exportation des données.

      Remarque

      Remplacez ${GRPC_ENDPOINT} et ${GRPC_ENDPOINT_TOKEN} par l'endpoint gRPC et le jeton d'authentification obtenus dans la section Prérequis de cette rubrique.

      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]

    2. Exécutez la commande suivante pour démarrer le collecteur OpenTelemetry :

      docker run -v $(pwd)/opentelemetry-config.yaml:/etc/otelcol-contrib/config.yaml otel/opentelemetry-collector-contrib:0.105.0

    Étape 4 : Consulter les traces NGINX

    Une fois les étapes précédentes terminées et NGINX redémarré, envoyez des requêtes à NGINX pour générer des traces. Connectez-vous ensuite à la console Managed Service for OpenTelemetry pour afficher les traces NGINX générées par OpenTelemetry.

    • Sur la page Applications, localisez l'application NGINX et cliquez sur son nom.89.jpg

    • Dans l'onglet Trace details, consultez les détails de la trace, notamment la durée de la requête, l'adresse IP du client et le code d'état HTTP. Si votre service backend est également connecté au service Managed Service for OpenTelemetry, les traces de NGINX et des services backend sont automatiquement associées pour offrir une vue intégrée.88.jpg

    Exemple

    L'exemple suivant montre comment collecter les données de trace de NGINX et d'un service backend, puis les envoyer au service Managed Service for OpenTelemetry.

    Étape 1 : Préparatifs

    Étape 2 : Créer les répertoires du projet

    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

    Créez les répertoires.

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

mkdir -p nginx_conf otel_conf backend

    Étape 3 : Créer les fichiers de configuration de NGINX

    1. Créez le fichier de configuration principal nginx.conf de 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. Créez le fichier de configuration 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

    Étape 4 : (Facultatif) Créer le fichier de configuration du collecteur OpenTelemetry

    Remarque

    Cette étape est requise uniquement pour le module ngx_otel_module V0.1.1 ou une version antérieure.

    Créez le fichier de configuration du collecteur OpenTelemetry. Ce fichier définit les méthodes de réception, de traitement et d'envoi des données.

    Remarque

    Remplacez ${GRPC_ENDPOINT} et ${GRPC_ENDPOINT_TOKEN} par l'endpoint gRPC et le jeton d'authentification obtenus dans la section Prérequis de cette rubrique.

    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

    Étape 5 : Créer un service backend avec Node.js

    1. Créez le fichier package.json. Ce fichier contient les informations de configuration du service backend, notamment le nom du service, la version du service et les dépendances.

      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. Créez le fichier main.js qui définit une application web Express basique.

      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. Créez le 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

    Étape 6 : Créer le fichier de configuration de Docker Compose

    Le fichier de configuration de Docker Compose définit les configurations d'une application multi-conteneurs, incluant NGINX servant de proxy inverse, le collecteur OpenTelemetry et un service backend Node.js. Ce fichier définit également les connexions réseau et les mappages de ports entre les composants.

    ngx_otel_module V0.1.2 or later

    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

    ngx_otel_module V0.1.1 or earlier

    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

    Étape 7 : Démarrer le service

    1. Exécutez la commande suivante dans le répertoire nginx-otel-demo :

      docker compose up -d

      Résultat attendu :

      ngx_otel_module V0.1.2 or later

      image

      ngx_otel_module V0.1.1 or earlier

      image (14).png

    2. Accédez au service backend.

      curl http://localhost:80/hello

      Résultat attendu :

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

    3. Connectez-vous à la console Managed Service for OpenTelemetry pour afficher les traces de NGINX et du service backend.

      Dans cet exemple, nginx s'affiche comme nom d'application pour NGINX sur la page Applications, et le nom du service backend est ot-nodejs-demo.

    FAQ

    1. Que faire si le téléchargement de nginx-module-otel échoue avec le message d'erreur « Unable to find a match: nginx-module-otel » ?

      Vérifiez si vous avez configuré le dépôt de packages NGINX. Si ce n'est pas le cas, configurez-le en suivant les instructions de la page nginx-otel.

    2. Que faire si NGINX ne démarre pas après avoir configuré le module ngx_otel_module dans le fichier de configuration de NGINX ?

      Exécutez la commande nginx -t pour vérifier la validité des configurations NGINX, ou consultez le message d'erreur dans les journaux NGINX.

      sudo tail -n 50 /var/log/nginx/error.log

    3. Que faire si aucune trace NGINX n'est disponible dans la console Managed Service for OpenTelemetry après avoir activé le module ngx_otel_module ?

      Vérifiez si la valeur du paramètre otel_exporter.endpoint est valide dans le fichier de configuration de NGINX. Cet endpoint se compose de l'adresse IP du serveur sur lequel le collecteur OpenTelemetry est déployé et du port utilisé par le collecteur OpenTelemetry pour recevoir les données envoyées via gRPC. Exemple : localhost:4317. Vous pouvez vérifier la validité des configurations en consultant les journaux NGINX. Si les erreurs illustrées dans la figure suivante sont signalées, l'endpoint n'est pas valide.

      image (15).png

    4. Que faire si les traces NGINX ne peuvent pas être associées à celles d'une autre application ?

      Vérifiez si otel_trace_context propagate; est configuré dans le fichier de configuration de NGINX, et si le protocole utilisé par l'application pour la propagation du contexte de trace est identique à celui utilisé par NGINX. Le module ngx_otel_module utilise le protocole OpenTelemetry et la spécification W3C pour la propagation du contexte de trace. Par conséquent, les traces NGINX ne peuvent être associées à celles de l'application que si cette dernière utilise également le protocole OpenTelemetry et la spécification W3C pour la propagation du contexte de trace.

    5. Le module ngx_otel_module affecte-t-il les performances de NGINX ?

      Le module ngx_otel_module est un module natif de NGINX. Selon l'équipe NGINX, l'impact de ce module sur les performances de NGINX est limité à 10 % à 15 %. Pour plus d'informations, consultez la page NGINX Native OpenTelemetry (OTel) Module.

    Références