Superviser les logs Systemd avec ClickStack

Intégration avec les systèmes existants

Surveillez les logs journald de votre système Linux actuel en exécutant l’OpenTelemetry Collector avec le journald receiver pour collecter les logs système et les envoyer à ClickStack via OTLP.

Si vous souhaitez d’abord tester cette intégration sans modifier votre configuration actuelle, passez à la section sur le jeu de données de démonstration.

Prérequis

Une instance ClickStack en cours d’exécution
Système Linux avec systemd (Ubuntu 16.04+, CentOS 7+, Debian 8+)
Docker ou Docker Compose installé sur le système surveillé

Obtenir la clé API ClickStack

L'OpenTelemetry Collector envoie les données vers le point de terminaison OTLP de ClickStack, qui nécessite une authentification.

Ouvrez HyperDX à l'URL de votre instance ClickStack (par ex. http://localhost:8080)
Créez un compte ou connectez-vous si nécessaire
Accédez à Team Settings → API Keys
Copiez votre Ingestion API Key

Définissez-la comme variable d'environnement :

export CLICKSTACK_API_KEY=your-api-key-here

Vérifier que le journal systemd est actif

Assurez-vous que votre système utilise systemd et dispose de journaux journalctl :

# Vérifier la version de systemd
systemctl --version

# Afficher les entrées récentes du journal
journalctl -n 20

# Vérifier l'utilisation disque du journal
journalctl --disk-usage

Si le journal est stocké uniquement en mémoire, activez le stockage persistant :

sudo mkdir -p /var/log/journal
sudo systemd-tmpfiles --create --prefix /var/log/journal
sudo systemctl restart systemd-journald

Créer la configuration de l'OpenTelemetry Collector

Créez un fichier de configuration pour l'OpenTelemetry Collector :

cat > otel-config.yaml << 'EOF'
receivers:
  journald:
    directory: /var/log/journal
    priority: info
    units:
      - sshd
      - nginx
      - docker
      - containerd
      - systemd

processors:
  batch:
    timeout: 10s
    send_batch_size: 10000
  
  resource:
    attributes:
      - key: service.name
        value: systemd-logs
        action: insert
      - key: host.name
        from_attribute: _HOSTNAME
        action: upsert
  
  attributes:
    actions:
      - key: unit
        from_attribute: _SYSTEMD_UNIT
        action: upsert
      - key: priority
        from_attribute: PRIORITY
        action: upsert

exporters:
  otlphttp:
    endpoint: ${CLICKSTACK_ENDPOINT}
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [journald]
      processors: [resource, attributes, batch]
      exporters: [otlphttp]
EOF

Déployer avec Docker Compose

Cet exemple montre comment déployer l'OTel Collector aux côtés de ClickStack :

services:
  clickstack:
    image: clickhouse/clickstack-all-in-one:latest
    ports:
      - "8080:8080"
      - "4317:4317"
      - "4318:4318"
    networks:
      - monitoring
  
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.115.1
    depends_on:
      - clickstack
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
      - CLICKSTACK_ENDPOINT=http://clickstack:4318
    volumes:
      - ./otel-config.yaml:/etc/otelcol/config.yaml:ro
      - /var/log/journal:/var/log/journal:ro
      - /run/log/journal:/run/log/journal:ro
      - /etc/machine-id:/etc/machine-id:ro
    command: ["--config=/etc/otelcol/config.yaml"]
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

Démarrez les services :

docker compose up -d

Vérifier les logs dans HyperDX

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

Accédez à la vue Search
Définissez la source sur Logs
Filtrez sur service.name:systemd-logs
Vous devriez voir des entrées de log structurées avec des champs comme unit, priority, MESSAGE, _HOSTNAME

Jeu de données de démonstration

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

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

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

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/systemd/systemd-demo.log

Créer une configuration de collector de démonstration

Créez un fichier de configuration pour la démonstration :

cat > systemd-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/systemd-demo/systemd-demo.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: "systemd-demo"

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

Exécuter ClickStack avec les données de démonstration

Démarrez ClickStack avec les logs de démonstration :

docker run -d --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)/systemd-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/systemd-demo.log:/tmp/systemd-demo/systemd-demo.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
Accédez à la vue Search et définissez la source sur Logs
Définissez l’intervalle de temps sur 2025-11-14 00:00:00 - 2025-11-17 00:00:00

Tableaux de bord et visualisations

Pour vous aider à démarrer la surveillance des logs systemd avec ClickStack, nous fournissons des visualisations essentielles pour les données du journal systemd.

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

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

Afficher le tableau de bord

Le tableau de bord comprend des visualisations pour :

Le volume de logs au fil du temps
Les principales unités systemd par nombre de logs
Les événements d’authentification SSH
Les défaillances de service
Les taux d’erreur

Dépannage

Aucun log n’apparaît dans HyperDX

Vérifiez si les logs parviennent à ClickHouse :

docker exec clickstack clickhouse-client --query "
SELECT COUNT(*) as log_count
FROM otel_logs
WHERE ServiceName = 'systemd-logs'
"

Si aucun résultat n’est renvoyé, vérifiez les logs du collector :

docker logs otel-collector | grep -i "error\|journald" | tail -20

erreur « journalctl introuvable »

Si vous voyez exec: "journalctl": executable file not found in $PATH :

L’image otel/opentelemetry-collector-contrib n’inclut pas journalctl. Vous pouvez :

Installer le collector sur l’hôte :

wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.115.0/otelcol-contrib_0.115.0_linux_amd64.tar.gz
tar -xzf otelcol-contrib_0.115.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/
otelcol-contrib --config=otel-config.yaml

Utilisez l’approche par exportation de texte (comme dans la démo) avec le receiver filelog qui lit les exports journald

Étapes suivantes

Configurez des alertes pour les événements système critiques (pannes de services, échecs d'authentification, arrêts OOM)
Créez des tableaux de bord supplémentaires pour des cas d'utilisation spécifiques (surveillance de la sécurité SSH, état de santé des services)
Filtrez sur des unités systemd spécifiques pour réduire le bruit et vous concentrer sur les services essentiels

Passage en production

Ce guide utilise un OpenTelemetry Collector distinct pour lire les logs systemd et les envoyer au point de terminaison OTLP de ClickStack, ce qui constitue l’approche recommandée en production.

Pour les environnements de production comportant plusieurs hôtes, envisagez :

de déployer le collector sous forme de DaemonSet dans Kubernetes
d’exécuter le collector en tant que service systemd sur chaque hôte
d’utiliser l’OpenTelemetry Operator pour automatiser le déploiement

Consultez Ingesting with OpenTelemetry pour découvrir les approches de déploiement en production.