Supervision des traces Nginx avec ClickStack

Le moyen le plus simple d’ajouter le traçage à Nginx consiste à utiliser l’image Nginx officielle avec la prise en charge d’OpenTelemetry intégrée.

Utilisation de l’image nginx:otel

Remplacez votre image Nginx actuelle par la version compatible OpenTelemetry :

# Dans votre docker-compose.yml ou Dockerfile
image: nginx:1.27-otel

Cette image inclut ngx_otel_module.so, préinstallé et prêt à l’emploi.

Ajoutez la configuration OpenTelemetry à votre fichier nginx.conf. Cette configuration charge le module et envoie les traces vers l’endpoint OTLP de ClickStack.

Commencez par récupérer votre clé API :

1. Ouvrez HyperDX à l’URL de votre instance ClickStack
2. Accédez à Settings → API Keys
3. Copiez votre clé API d’ingestion
4. Définissez-la comme variable d’environnement : export CLICKSTACK_API_KEY=your-api-key-here

Ajoutez ceci à votre nginx.conf :

load_module modules/ngx_otel_module.so;

events {
    worker_connections 1024;
}

http {
    # Configuration de l’exporter OpenTelemetry
    otel_exporter {
        endpoint <clickstack-host>:4317;
        header authorization ${CLICKSTACK_API_KEY};
    }
    
    # Nom du service pour identifier cette instance Nginx
    otel_service_name "nginx-proxy";
    
    # Activer le traçage
    otel_trace on;
    
    server {
        listen 80;
        
        location / {
            # Activer le traçage pour cet emplacement
            otel_trace_context propagate;
            otel_span_name "$request_method $uri";
            
            # Ajouter des détails de requête aux traces
            otel_span_attr http.status_code $status;
            otel_span_attr http.request.method $request_method;
            otel_span_attr http.route $uri;
            
            # Votre configuration de proxy ou d’application existante
            proxy_pass http://your-backend;
        }
    }
}

Si vous exécutez Nginx dans Docker, transmettez la variable d’environnement au conteneur :

services:
  nginx:
    image: nginx:1.27-otel
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

Remplacez <clickstack-host> par le nom d’hôte ou l’adresse IP de votre instance ClickStack.

Comprendre la configuration

Ce qui est tracé : Chaque requête vers Nginx crée un span de trace affichant :

• la méthode et le chemin de la requête
• le code d’état HTTP
• la durée de la requête
• l’horodatage

Attributs de span : Les directives otel_span_attr ajoutent des métadonnées à chaque trace, ce qui vous permet de filtrer et d’analyser les requêtes dans HyperDX par code d’état, méthode, route, etc.

Après avoir effectué ces modifications, testez votre configuration Nginx :

nginx -t

Si le test réussit, rechargez Nginx :

# Pour Docker
docker-compose restart nginx

# Pour systemd
sudo systemctl reload nginx

Une fois la configuration en place, connectez-vous à HyperDX et vérifiez que les traces arrivent bien. Vous devriez voir quelque chose comme ceci ; si vous ne voyez pas de traces, essayez d’ajuster l’intervalle de temps :

Si ClickStack n’est pas encore en cours d’exécution, démarrez-le avec :

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

Attendez environ 30 secondes que ClickStack soit complètement initialisé avant de continuer.

• Port 8080 : interface web HyperDX
• Port 4317 : endpoint OTLP gRPC (utilisé par le module nginx)
• Port 4318 : endpoint OTLP HTTP (utilisé pour les traces de démonstration)

Téléchargez le fichier d’exemple de traces et mettez les horodatages à l’heure actuelle :

# Télécharger les traces
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nginx-traces-sample.json

Le jeu de données comprend :

• 1 000 spans de trace avec une chronologie réaliste
• 9 endpoints différents avec des profils de trafic variés
• ~93 % de réussite (200), ~3 % d’erreurs client (404), ~4 % d’erreurs serveur (500)
• Des latences allant de 10ms à 800ms
• Les profils de trafic d’origine sont conservés, mais décalés à l’heure actuelle

Définissez votre clé API comme variable d’environnement (si ce n’est pas déjà fait) :

export CLICKSTACK_API_KEY=your-api-key-here

Obtenir votre clé API :

1. Ouvrez HyperDX à l’URL de votre ClickStack
2. Accédez à Settings → API Keys
3. Copiez votre clé API d’ingestion

Envoyez ensuite les traces à ClickStack :

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nginx-traces-sample.json

Vous devriez voir une réponse comme {"partialSuccess":{}}, indiquant que les traces ont bien été envoyées. Les 1 000 traces seront toutes ingérées dans ClickStack.

1. Ouvrez HyperDX et connectez-vous à votre compte (vous devrez peut-être d’abord en créer un)
2. Accédez à la vue Search et définissez la source sur Traces
3. Réglez l’intervalle de temps sur 2025-10-25 13:00:00 - 2025-10-28 13:00:00

Voici ce que vous devriez voir dans votre vue Search :

Télécharger le fichier de configuration du tableau de bord.

1. Ouvrez HyperDX et accédez à la section Dashboards.
2. Cliquez sur "Import Dashboard" dans le coin supérieur droit, sous les points de suspension.

3. Téléversez le fichier nginx-trace-dashboard.json, puis cliquez sur Finish Import.