> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Superviser les logs Nginx avec ClickStack

> Surveillance de Nginx avec ClickStack

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **En bref**

  Collectez et visualisez les logs d’accès Nginx (format JSON) dans ClickStack à l’aide du receiver OTel `filelog`. Inclut un jeu de données de démonstration et un tableau de bord préconfiguré.
</Info>

<div id="existing-nginx">
  ## Intégration à une installation Nginx existante
</div>

Cette section explique comment configurer votre installation Nginx existante pour envoyer les logs vers ClickStack en modifiant la configuration du ClickStack OTel collector.
Si vous souhaitez tester l’intégration avant de configurer votre propre environnement, vous pouvez utiliser notre configuration préconfigurée et des données d’exemple dans la [section suivante](/fr/clickstack/integration-examples/nginx-logs#demo-dataset).

<div id="prerequisites">
  ##### Prérequis
</div>

* Une instance ClickStack en cours d’exécution
* Une installation Nginx existante
* Un accès permettant de modifier les fichiers de configuration de Nginx

<Steps>
  <Step>
    #### Configurer le format des logs Nginx

    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` :

    ```nginx theme={null}
    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.
  </Step>

  <Step>
    #### Créer une configuration personnalisée pour l’OTel collector

    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 :

    ```yaml theme={null}
    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é

    <Note>
      - Vous définissez uniquement de nouveaux receivers et pipelines dans la configuration personnalisée
      - Les processors (memory\_limiter, transform, batch) et exporters (clickhouse) sont déjà définis dans la configuration de base de ClickStack ; vous vous contentez de les référencer par leur nom
      - L’opérateur time\_parser extrait les horodatages du champ time\_local de Nginx afin de préserver l’heure d’origine des logs
      - Les pipelines achemine les données de vos receivers vers le ClickHouse exporter via les processors existants
    </Note>
  </Step>

  <Step>
    #### Configurer ClickStack pour charger une configuration personnalisée

    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 :

    ```yaml theme={null}
    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 :

    ```bash theme={null}
    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
    ```

    <Note>
      Assurez-vous que le collecteur ClickStack dispose des autorisations nécessaires pour lire les fichiers journaux de nginx. En production, utilisez des montages en lecture seule (:ro) et appliquez le principe du moindre privilège.
    </Note>
  </Step>

  <Step>
    #### Vérifier les logs dans HyperDX

    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 :

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/nginx-logs-search-view.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=b1725490b1d1543607d70c290f321dc8" alt="Vue Log" width="3838" height="1938" data-path="images/clickstack/nginx-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/log-view.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=07094bb7c4565975da39434c359755a6" alt="Vue Log" width="3838" height="1934" data-path="images/clickstack/log-view.png" />
  </Step>
</Steps>

<div id="demo-dataset">
  ## Jeu de données de démonstration
</div>

Pour les utilisateurs qui souhaitent tester l’intégration nginx avant de configurer leurs systèmes de production, nous fournissons un jeu de données d’exemple composé de logs d’accès nginx pré-générés avec des schémas de trafic réalistes.

<Steps>
  <Step>
    #### Télécharger le jeu de données d’exemple

    ```bash theme={null}
    # 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
  </Step>

  <Step>
    #### Créer une configuration de collector de test

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

    ```yaml theme={null}
    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
    ```
  </Step>

  <Step>
    #### Exécuter ClickStack avec la configuration de démonstration

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

    ```bash theme={null}
    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
    ```
  </Step>

  <Step>
    #### Vérifier les logs dans HyperDX

    Une fois ClickStack en cours d’exécution :

    1. Ouvrez [HyperDX](http://localhost:8080/) 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 :

    <Info>
      **Affichage du fuseau horaire**

      HyperDX affiche les timestamps dans le fuseau horaire local de votre navigateur. Les données de démonstration couvrent la période du 2025-10-20 11:00:00 au 2025-10-21 11:00:00 UTC. Cet intervalle de temps large garantit que vous verrez les logs de démonstration, quel que soit votre lieu. Une fois les logs affichés, vous pouvez réduire l’intervalle à 24 heures pour obtenir des visualisations plus claires.
    </Info>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/nginx-logs-search-view.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=b1725490b1d1543607d70c290f321dc8" alt="Log view" width="3838" height="1938" data-path="images/clickstack/nginx-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/log-view.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=07094bb7c4565975da39434c359755a6" alt="Log view" width="3838" height="1934" data-path="images/clickstack/log-view.png" />
  </Step>
</Steps>

<div id="dashboards">
  ## Tableaux de bord et visualisations
</div>

Pour vous aider à commencer à surveiller Nginx avec ClickStack, nous fournissons des visualisations essentielles pour les logs Nginx.

<Steps>
  <Step>
    #### <TrackedLink href={'/fr/examples/nginx-logs-dashboard.json'} download="nginx-logs-dashboard.json" eventName="docs.nginx_logs_monitoring.dashboard_download">Télécharger</TrackedLink> la configuration du tableau de bord
  </Step>

  <Step>
    #### Importer le tableau de bord préconfiguré

    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.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/import-dashboard.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=916537724b4bfd47afb8cccdb5dc4902" alt="Importer le tableau de bord" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/finish-nginx-logs-import.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=d1a78efafcce283031c5371bcc566880" alt="Terminer l’importation" width="3812" height="1906" data-path="images/clickstack/finish-nginx-logs-import.png" />
  </Step>

  <Step>
    #### Le tableau de bord sera créé avec toutes les visualisations préconfigurées

    <Note>
      Pour le jeu de données de démonstration, définissez l’intervalle de temps sur **2025-10-20 11:00:00 - 2025-10-21 11:00:00 (UTC)** (à ajuster selon votre fuseau horaire local). Par défaut, aucun intervalle de temps ne sera défini pour le tableau de bord importé.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/7bmhpXp9q5MTUEeP/images/clickstack/nginx-logs-dashboard.png?fit=max&auto=format&n=7bmhpXp9q5MTUEeP&q=85&s=fce941ca35794d41475887e8244e4e50" alt="Exemple de tableau de bord" width="3812" height="1906" data-path="images/clickstack/nginx-logs-dashboard.png" />
  </Step>
</Steps>

<div id="troubleshooting">
  ## Dépannage
</div>

<div id="troubleshooting-not-loading">
  ### La configuration personnalisée ne se charge pas
</div>

* Vérifiez que la variable d’environnement CUSTOM\_OTELCOL\_CONFIG\_FILE est correctement définie

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

* Vérifiez que le fichier de configuration personnalisé est bien monté à l’emplacement /etc/otelcol-contrib/custom.config.yaml

```bash theme={null}
docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
```

* Consultez le contenu de la config personnalisée pour vérifier qu'il est bien lisible

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
```

<div id="no-logs">
  ### Aucun log ne s’affiche dans HyperDX
</div>

* Assurez-vous que nginx écrit des logs au format JSON

```bash theme={null}
tail -f /var/log/nginx/access.log
```

* Vérifiez que le collector peut lire les logs

```bash theme={null}
docker exec `<container>` cat /var/log/nginx/access.log
```

* Vérifiez que la configuration effective inclut votre receiver filelog

```bash theme={null}
docker exec `<container>` cat /etc/otel/supervisor-data/effective.yaml | grep filelog
```

* Recherchez des erreurs dans les logs du collector

```bash theme={null}
docker exec `<container>` cat /etc/otel/supervisor-data/agent.log
```

<div id="next-steps">
  ## Prochaines étapes
</div>

* Configurez des [alertes](/fr/clickstack/features/alerts) pour les métriques critiques (taux d’erreur, seuils de latence)
* Créez des [tableaux de bord](/fr/clickstack/features/dashboards/overview) supplémentaires pour des cas d’usage spécifiques (surveillance des API, événements de sécurité)

<div id="going-to-production">
  ## Mise en production
</div>

Ce guide s'appuie sur l'OpenTelemetry Collector intégré à ClickStack pour une mise en place rapide. Pour les déploiements en production, nous vous recommandons d'exécuter votre propre OTel Collector et d'envoyer les données vers l'endpoint OTLP de ClickStack. Consultez [Envoi de données OpenTelemetry](/fr/clickstack/ingesting-data/opentelemetry) pour la configuration à utiliser en production.