Superviser les logs Nginx avec ClickStack

Commencez par configurer Nginx pour qu'il génère des logs au format JSON afin d'en faciliter l'analyse. Ajoutez cette définition du format des logs à votre nginx.conf :

Le fichier nginx.conf se trouve généralement à l'emplacement suivant :

• Linux (apt/yum) : /etc/nginx/nginx.conf
• macOS (Homebrew) : /usr/local/etc/nginx/nginx.conf ou /opt/homebrew/etc/nginx/nginx.conf
• Docker : la configuration est généralement montée comme volume

Ajoutez cette définition du format des logs au bloc http :

http {
    log_format json_combined escape=json
    '{'
      '"time_local":"$time_local",'
      '"remote_addr":"$remote_addr",'
      '"request_method":"$request_method",'
      '"request_uri":"$request_uri",'
      '"status":$status,'
      '"body_bytes_sent":$body_bytes_sent,'
      '"request_time":$request_time,'
      '"upstream_response_time":"$upstream_response_time",'
      '"http_referer":"$http_referer",'
      '"http_user_agent":"$http_user_agent"'
    '}';

    access_log /var/log/nginx/access.log json_combined;
    error_log /var/log/nginx/error.log warn;
}

Une fois cette modification effectuée, rechargez Nginx.

ClickStack vous permet d’étendre la configuration de base de l’OpenTelemetry Collector en montant un fichier de configuration personnalisé et en définissant une variable d’environnement. La configuration personnalisée est fusionnée avec la configuration de base gérée par HyperDX via OpAMP.

Créez un fichier nommé nginx-monitoring.yaml avec la configuration suivante :

receivers:
  filelog:
    include:
      - /var/log/nginx/access.log
      - /var/log/nginx/error.log
    start_at: end 
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx"

service:
  pipelines:
    logs/nginx:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Cette configuration :

• Lit les logs Nginx depuis leurs emplacements standard
• Analyse les entrées de log JSON
• Extrait et préserve les horodatages d’origine des logs
• Ajoute l’attribut source : Nginx pour le filtrage dans HyperDX
• Achemine les logs vers le ClickHouse exporter via un pipeline dédié

Pour activer une configuration personnalisée du collecteur dans votre déploiement ClickStack existant, vous devez :

1. Monter le fichier de configuration personnalisé à l’emplacement /etc/otelcol-contrib/custom.config.yaml
2. Définir la variable d’environnement CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
3. Monter vos répertoires de logs Nginx pour que le collecteur puisse les lire

Option 1 : Docker Compose

Mettez à jour la configuration de votre déploiement ClickStack :

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... other volumes ...

Option 2 : Docker Run (image tout-en-un)

Si vous utilisez l'image tout-en-un avec docker run :

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/nginx:/var/log/nginx:ro \
  clickhouse/clickstack-all-in-one:latest

Une fois la configuration terminée, connectez-vous à HyperDX et vérifiez que les logs remontent bien :

1. Accédez à la vue Search
2. Définissez la source sur Logs, puis vérifiez que vous voyez des entrées de logs avec des champs tels que request, request_time, upstream_response_time, etc.

Voici un exemple de ce que vous devriez voir :

# Télécharger les logs
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

Le jeu de données comprend :

• Des entrées de log avec des schémas de trafic réalistes
• Divers endpoints et méthodes HTTP
• Un mélange de requêtes réussies et d’erreurs
• Des temps de réponse et des volumes d’octets réalistes

Créez un fichier nommé nginx-demo.yaml avec la configuration suivante :

cat > nginx-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/nginx-demo/access.log
    start_at: beginning  # Lire depuis le début pour les données de démonstration
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx-demo"

service:
  pipelines:
    logs/nginx-demo:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Exécutez ClickStack avec les logs et la configuration de démonstration :

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/access.log:/tmp/nginx-demo/access.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Une fois ClickStack en cours d’exécution :

1. Ouvrez HyperDX et connectez-vous à votre compte (vous devrez peut-être d’abord en créer un)
2. Accédez à la Search view et définissez la source sur Logs
3. Définissez l’intervalle de temps sur 2025-10-19 11:00:00 - 2025-10-22 11:00:00

Voici ce que vous devriez voir dans la Search view :

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 l’angle supérieur droit, sous les points de suspension.

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