Supervision des logs hôtes avec ClickStack

Intégration avec des hôtes existants

Cette section explique comment configurer vos hôtes existants pour envoyer les logs système à ClickStack, en modifiant la configuration du ClickStack OTel collector pour lire tous les fichiers de log système (syslog, auth, kernel, daemon et journaux d’application).

Si vous souhaitez tester l’intégration des logs hôte avant de configurer votre propre installation existante, vous pouvez utiliser notre configuration préconfigurée et nos données d’exemple dans la section "Jeu de données de démonstration".

Prérequis

Instance ClickStack en cours d’exécution
Système avec des fichiers syslog
Accès requis pour modifier les fichiers de configuration de ClickStack

Vérifiez la présence des fichiers syslog

Commencez par vérifier que votre système génère bien des fichiers syslog :

# Check if syslog files exist (Linux)
ls -la /var/log/syslog /var/log/messages

# Or on macOS
ls -la /var/log/system.log

# View recent entries
tail -20 /var/log/syslog

Emplacements courants des fichiers syslog :

Ubuntu/Debian: /var/log/syslog
RHEL/CentOS/Fedora: /var/log/messages
macOS: /var/log/system.log

Créer une configuration personnalisée de 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.

Créez un fichier nommé host-logs-monitoring.yaml avec la configuration de votre système :

receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
      
      - type: add
        field: attributes.source
        value: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

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

receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /var/log/messages
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%b %d %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

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

receivers:
  filelog/syslog:
    include:
      - /var/log/system.log
      - /host/private/var/log/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%b %d %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

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

Toutes les configurations :

Lire les fichiers syslog depuis leurs emplacements standard
Analyser le format syslog pour extraire des champs structurés (horodatage, nom d’hôte, unité/service, PID, message)
Préserver les horodatages d’origine des logs
Ajouter l’attribut source: host-logs pour le filtrage dans HyperDX
Acheminer les logs vers le ClickHouse exporter via un pipeline dédié

Configurer ClickStack pour charger une configuration personnalisée

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

Monter le fichier de configuration personnalisé sur /etc/otelcol-contrib/custom.config.yaml
Définir la variable d’environnement CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Monter votre répertoire syslog afin que le collecteur puisse y accéder

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:
      - ./host-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log:/var/log: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)/host-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log:/var/log:ro \
  clickhouse/clickstack-all-in-one:latest

Vérifier les logs dans HyperDX

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

Accédez à la vue Search
Définissez la source sur Logs
Filtrez sur source:host-logs pour afficher les logs spécifiques à l’hôte
Vous devriez voir des entrées de logs structurées avec des champs tels que unit, hostname, pid, message, etc.

Jeu de données de démonstration

Pour les utilisateurs qui souhaitent tester l’intégration des logs hôte avant de configurer leurs systèmes de production, nous fournissons un jeu de données d’exemple contenant des logs système pré-générés aux schémas réalistes.

Télécharger le jeu de données d’exemple

Téléchargez le fichier de log d’exemple :

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log

Le jeu de données comprend :

Séquence de démarrage du système
Activité de connexion SSH (tentatives réussies et échouées)
Incident de sécurité (attaque par force brute avec réponse de fail2ban)
Maintenance planifiée (tâches cron, anacron)
Redémarrages de service (rsyslog)
Messages du noyau et activité du pare-feu
Mélange d’opérations normales et d’événements notables

Créer une configuration de collector de test

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

cat > host-logs-demo.yaml << 'EOF'
receivers:
  filelog/journal:
    include:
      - /tmp/host-demo/journal.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%Y-%m-%dT%H:%M:%S%z'
      
      - type: add
        field: attributes.source
        value: "host-demo"
      
      - type: add
        field: resource["service.name"]
        value: "host-demo"

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

Exécuter ClickStack avec la configuration de démonstration

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

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)/host-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/journal.log:/tmp/host-demo/journal.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Vérifier les logs dans HyperDX

Une fois ClickStack démarré :

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

Tableaux de bord et visualisation

Pour vous aider à démarrer la surveillance des logs hôte avec ClickStack, nous fournissons des visualisations essentielles pour les logs système.

Télécharger la configuration du tableau de bord

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

Importer le tableau de bord préconfiguré

Ouvrez HyperDX et accédez à la section Dashboards
Cliquez sur Import Dashboard dans le coin supérieur droit, dans le menu à trois points

Téléversez le fichier host-logs-dashboard.json et cliquez sur Finish Import

Afficher le tableau de bord

Le tableau de bord sera créé avec toutes les visualisations préconfigurées :

Les principales visualisations sont les suivantes :

Volume des logs au fil du temps, par niveau de gravité
Principales unités systemd générant des logs
Activité des connexions SSH (réussies ou échouées)
Activité du pare-feu (bloquées ou autorisées)
Événements de sécurité (connexions échouées, bannissements, blocages)
Activité de redémarrage des services

Dépannage

La config personnalisée ne se charge pas

Vérifiez que la variable d'environnement est définie :

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Vérifiez que le fichier de configuration personnalisé est bien monté et lisible :

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml | head -10

Aucun log ne s’affiche dans HyperDX

Vérifiez que les fichiers syslog existent et qu’ils sont bien alimentés :

# Check if syslog exists
ls -la /var/log/syslog /var/log/messages

# Verify logs are being written
tail -f /var/log/syslog

Vérifiez que le collector peut lire les logs :

docker exec <container> cat /var/log/syslog | head -20

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

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Vérifiez s’il y a des erreurs dans les logs du collector :

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i "filelog\|syslog"

Si vous utilisez le jeu de données de démonstration, vérifiez que le fichier de log est accessible :

docker exec <container> cat /tmp/host-demo/journal.log | wc -l

Les logs ne sont pas correctement analysés

Vérifiez que le format syslog correspond à la configuration choisie :

Pour Linux moderne (Ubuntu 24.04+) :

# Should show ISO8601 format: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

Pour Legacy Linux ou macOS :

# Should show traditional format: Nov 17 14:16:16
tail -5 /var/log/syslog
# or
tail -5 /var/log/system.log

Si ce n’est pas le bon format, sélectionnez l’onglet de configuration approprié dans la section Créer une configuration personnalisée pour l’OTel collector.

Étapes suivantes

Configurez des alertes pour les événements système critiques (défaillances de service, échecs d’authentification, alertes liées au disque)
Filtrez sur des unités spécifiques pour surveiller certains services
Corrélez les logs hôte avec les logs d’application pour un dépannage complet
Créez des tableaux de bord personnalisés pour la surveillance de la sécurité (tentatives SSH, utilisation de sudo, blocages du pare-feu)

Passer en production

Ce guide s'appuie sur l'OpenTelemetry Collector intégré à ClickStack pour une configuration rapide. Pour les déploiements en production, nous vous recommandons d'exécuter votre propre OTel Collector et d'envoyer les données vers le point de terminaison OTLP de ClickStack. Consultez Envoyer des données OpenTelemetry pour la configuration de production.