Passer au contenu principal
En brefCollectez et visualisez les logs système d’EC2 dans ClickStack à l’aide de l’OpenTelemetry Collector, avec enrichissement automatique des métadonnées EC2 (ID d’instance, région, AZ, type d’instance). Inclut un jeu de données de démonstration et un tableau de bord préconfiguré.

​
Intégration avec une instance EC2 existante

Cette section explique comment installer OpenTelemetry Collector sur vos instances EC2 pour collecter les logs système et les envoyer à ClickStack avec un enrichissement automatique des métadonnées EC2. Cette architecture distribuée est adaptée à la production et passe à l’échelle sur plusieurs instances.
Vous exécutez ClickStack sur la même instance EC2 ?Si ClickStack s’exécute sur la même instance EC2 dont vous souhaitez surveiller les logs, vous pouvez utiliser l’approche tout-en-un, comme dans le guide des logs d’hôte génériques. Montez /var/log dans le conteneur ClickStack et ajoutez le processeur resourcedetection à votre config personnalisée pour capturer automatiquement les métadonnées EC2. Ce guide se concentre sur l’architecture distribuée, plus courante pour les déploiements en production.
Si vous souhaitez tester l’intégration des logs d’hôte EC2 avant de configurer votre instance de production, 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 (peut être sur site, dans le Cloud ou en local)
  • Instance EC2 en cours d’exécution (Ubuntu, Amazon Linux ou autre distribution Linux)
  • Connectivité réseau entre l’instance EC2 et l’endpoint OTLP de ClickStack (port 4318 pour HTTP ou 4317 pour gRPC)
  • Service de métadonnées de l’instance EC2 accessible (activé par défaut)
1

​
Vérifiez que les métadonnées EC2 sont accessibles

Depuis votre instance EC2, vérifiez que le service de métadonnées est accessible :
# Get metadata token (IMDSv2)
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# Verify instance metadata
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/placement/region
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-type
Vous devriez voir votre ID d’instance, la région et le type d’instance. Si ces commandes échouent, vérifiez :
  • Que le service de métadonnées d’instance est activé
  • Qu’IMDSv2 n’est pas bloqué par des groupes de sécurité ou des ACL réseau
  • Que vous exécutez ces commandes depuis l’instance EC2 elle-même
Les métadonnées EC2 sont accessibles à l’adresse http://169.254.169.254 depuis l’instance. Le processeur resourcedetection d’OpenTelemetry utilise ce point de terminaison pour enrichir automatiquement les logs avec le contexte cloud.
2

​
Vérifiez que les fichiers syslog existent

Vérifiez que votre instance EC2 génère des fichiers syslog :
# Ubuntu instances
ls -la /var/log/syslog

# Amazon Linux / RHEL instances
ls -la /var/log/messages

# View recent entries
tail -20 /var/log/syslog
# or
tail -20 /var/log/messages
3

​
Installer l’OpenTelemetry Collector

Installez la distribution Contrib de l’OpenTelemetry Collector sur votre instance EC2 :
# Download the latest release
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# Extract and install
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# Verify installation
otelcol-contrib --version
4

​
Créer la configuration du collector

Créez un fichier de configuration pour l’OpenTelemetry Collector dans /etc/otelcol-contrib/config.yaml :
sudo mkdir -p /etc/otelcol-contrib
Choisissez la configuration en fonction de votre distribution Linux :
sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
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: "ec2-host-logs"

processors:
  resourcedetection:
    detectors: [ec2, system]
    timeout: 5s
    override: false
    ec2:
      tags:
        - ^Name
        - ^Environment
        - ^Team
  
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  otlphttp:
    endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
    headers:
      authorization: "${env:CLICKSTACK_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [filelog/syslog]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
EOF

Remplacez les éléments suivants dans la configuration :
  • YOUR_CLICKSTACK_HOST : le nom d’hôte ou l’adresse IP sur lequel ClickStack s’exécute
  • Pour les tests en local, vous pouvez utiliser un tunnel SSH (voir la section Dépannage)
Cette configuration :
  • Lit les fichiers de log système aux emplacements standard (/var/log/syslog pour Ubuntu, /var/log/messages pour Amazon Linux/RHEL)
  • Analyse le format syslog pour en extraire des champs structurés (horodatage, nom d’hôte, unité/service, PID, message)
  • Détecte et ajoute automatiquement les métadonnées EC2 à l’aide du processeur resourcedetection
  • Peut inclure les tags EC2 (Name, Environment, Team) s’ils sont présents
  • Envoie les logs à ClickStack via OTLP HTTP
Enrichissement des métadonnées EC2Le processeur resourcedetection ajoute automatiquement les attributs suivants à chaque log :
  • cloud.provider: “aws”
  • cloud.platform: “aws_ec2”
  • cloud.region: région AWS (p. ex., “us-east-1”)
  • cloud.availability_zone: zone de disponibilité (p. ex., “us-east-1a”)
  • cloud.account.id: ID du compte AWS
  • host.id: ID d’instance EC2 (p. ex., “i-1234567890abcdef0”)
  • host.type: type d’instance (p. ex., “t3.medium”)
  • host.name: nom d’hôte de l’instance
5

​
Définir la clé API ClickStack

Exportez votre clé API ClickStack comme variable d’environnement :
export CLICKSTACK_API_KEY="your-api-key-here"
Pour que cela soit conservé après les redémarrages, ajoutez-le au profil de votre shell :
echo 'export CLICKSTACK_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
6

​
Démarrer le collector

Démarrez l’OpenTelemetry Collector :
CLICKSTACK_API_KEY="your-api-key-here" /usr/local/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml
Pour une utilisation en productionConfigurez le collecteur pour qu’il s’exécute en tant que service systemd afin qu’il démarre automatiquement au démarrage du système et redémarre en cas d’échec. Consultez la documentation de l’OpenTelemetry Collector pour plus de détails.
7

​
Vérifier les logs dans HyperDX

Une fois le collector en cours d’exécution, connectez-vous à HyperDX et vérifiez que les logs remontent avec les métadonnées EC2 :
  1. Accédez à la vue Search
  2. Définissez la source sur Logs
  3. Filtrez sur source:ec2-host-logs
  4. Cliquez sur un log pour l’ouvrir
  5. Vérifiez que les métadonnées EC2 apparaissent dans les resource attributes :
    • cloud.provider
    • cloud.region
    • host.id (ID d’instance)
    • host.type (type d’instance)
    • cloud.availability_zone

​
Jeu de données de démonstration

Pour les utilisateurs qui souhaitent tester l’intégration des logs d’hôte EC2 avant de configurer leurs instances de production, nous mettons à disposition un jeu de données d’exemple contenant des métadonnées EC2 simulées.
1

​
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/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 intervention de fail2ban)
  • Maintenance planifiée (tâches cron, anacron)
  • Redémarrages de services (rsyslog)
  • Messages du noyau et activité du pare-feu
  • Mélange d’opérations normales et d’événements marquants
2

​
Créer la configuration du collector de test

Créez un fichier nommé ec2-host-logs-demo.yaml contenant la configuration suivante :
cat > ec2-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: "ec2-demo"

processors:
  # Simulate EC2 metadata for demo (no real EC2 instance required)
  resource:
    attributes:
      - key: service.name
        value: "ec2-demo"
        action: insert
      - key: cloud.provider
        value: "aws"
        action: insert
      - key: cloud.platform
        value: "aws_ec2"
        action: insert
      - key: cloud.region
        value: "us-east-1"
        action: insert
      - key: cloud.availability_zone
        value: "us-east-1a"
        action: insert
      - key: host.id
        value: "i-0abc123def456789"
        action: insert
      - key: host.type
        value: "t3.medium"
        action: insert
      - key: host.name
        value: "prod-web-01"
        action: insert

service:
  pipelines:
    logs/ec2-demo:
      receivers: [filelog/journal]
      processors:
        - resource
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF
Pour la démonstration, nous ajoutons manuellement les métadonnées EC2 à l’aide du processeur resource. En production, avec de véritables instances EC2, utilisez le processeur resourcedetection, qui interroge automatiquement l’API des métadonnées EC2.
3

​
Exécuter ClickStack avec la configuration de démonstration

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

​
Vérifier les logs dans HyperDX

Une fois le collector démarré :
  1. Ouvrez HyperDX et connectez-vous à votre compte (vous devrez peut-être d’abord en créer un)
  2. Accédez à la vue de recherche et définissez la source sur Logs
  3. Définissez l’intervalle de temps sur 2025-11-10 00:00:00 - 2025-11-13 00:00:00
  4. Filtrez sur source:ec2-demo
  5. Développez une entrée de log pour afficher les métadonnées EC2 dans les attributs de ressource
Affichage du fuseau horaireHyperDX affiche les timestamps dans le fuseau horaire local de votre navigateur. Les données de démonstration couvrent 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC). Cet intervalle de temps étendu garantit que vous verrez les logs de démonstration, quel que soit votre emplacement. Une fois les logs affichés, vous pouvez réduire l’intervalle à une période de 24 heures pour obtenir des visualisations plus claires.
Vous devriez voir des logs avec un contexte EC2 simulé, notamment :
  • ID d’instance : i-0abc123def456789
  • Région : us-east-1
  • Zone de disponibilité : us-east-1a
  • Type d’instance : t3.medium

​
Tableaux de bord et visualisations

Pour vous aider à commencer à surveiller les logs d’hôtes EC2 avec ClickStack, nous fournissons des visualisations essentielles avec le contexte cloud.
1

​
la configuration du tableau de bord

2

​
Importer le tableau de bord préconfiguré

  1. Ouvrez HyperDX et accédez à la section Tableaux de bord
  2. Cliquez sur Importer le tableau de bord dans le coin supérieur droit, sous le menu à trois points
  1. Téléversez le fichier host-logs-dashboard.json et cliquez sur Terminer l’import
3

​
Afficher le tableau de bord

Le tableau de bord sera créé avec toutes les visualisations préconfigurées :Vous pouvez filtrer les visualisations du tableau de bord en fonction du contexte EC2 :
  • cloud.region:us-east-1 - Afficher les logs d’une région spécifique
  • host.type:t3.medium - Filtrer par type d’instance
  • host.id:i-0abc123def456 - Logs d’une instance spécifique
Pour le jeu de données de démonstration, définissez l’intervalle de temps sur 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC) (ajustez-le en fonction de votre fuseau horaire local). Le tableau de bord importé n’aura pas d’intervalle de temps défini par défaut.

​
Dépannage

​
Les métadonnées EC2 n’apparaissent pas dans les logs

Vérifiez que le service de métadonnées EC2 est accessible : 
# Get metadata token
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# Test metadata endpoint
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id
En cas d’échec, vérifiez :
  • Le service de métadonnées d’instance est activé
  • IMDSv2 n’est pas bloqué par des groupes de sécurité
  • Le collector s’exécute sur l’instance EC2 elle-même
Vérifiez les logs du collector pour repérer les erreurs liées aux métadonnées : 
# If running as systemd service
sudo journalctl -u otelcol-contrib -f | grep -i "ec2\|metadata\|resourcedetection"

# If running in foreground, check stdout

​
Aucun log ne s’affiche dans HyperDX

Vérifiez que les fichiers syslog existent et qu’ils sont bien alimentés : 
ls -la /var/log/syslog /var/log/messages
tail -f /var/log/syslog
Vérifiez que le collector peut lire les fichiers de log : 
cat /var/log/syslog | head -20
Vérifiez la connectivité réseau avec ClickStack : 
# Test OTLP endpoint
curl -v http://YOUR_CLICKSTACK_HOST:4318/v1/logs

# Should get a response (even if error, means endpoint is reachable)
Consultez les logs du collector pour repérer d’éventuelles erreurs : 
# If running in foreground
# Look for error messages in stdout

# If running as systemd service
sudo journalctl -u otelcol-contrib -f | grep -i "error\|failed"

​
Les logs sont mal analysés

Vérifiez le format de votre syslog : Pour Ubuntu 24.04+ : 
# Should show ISO8601 format: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog
Pour Amazon Linux 2 / Ubuntu 20.04 : 
# Should show traditional format: Nov 17 14:16:16
tail -5 /var/log/messages
Si votre format ne correspond pas, utilisez l’onglet de configuration approprié dans la section Créer une configuration du collecteur, selon votre distribution.

​
Le collecteur ne démarre pas comme service systemd

Vérifiez l’état du service : 
sudo systemctl status otelcol-contrib
Consultez les logs détaillés : 
sudo journalctl -u otelcol-contrib -n 50
Problèmes courants :
  • API key incorrectement définie dans l’environnement
  • Erreurs de syntaxe dans le fichier de configuration
  • Problèmes d’autorisation lors de la lecture des fichiers de log

​
Étapes suivantes

  • Configurez des alertes pour les événements système critiques (pannes de service, échecs d’authentification, alertes liées au disque)
  • Filtrez selon les attributs des métadonnées EC2 (région, type d’instance, ID d’instance) afin de surveiller des ressources spécifiques
  • Corrélez les logs d’hôte EC2 avec les logs d’application pour un dépannage plus 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)

​
Passage en production

Ce guide installe l’OpenTelemetry Collector directement sur des instances EC2, ce qui correspond au modèle recommandé en production pour la supervision au niveau de l’hôte. Pour gérer des collectors sur un grand nombre d’instances, envisagez d’utiliser des outils de gestion de configuration (Ansible, Chef, Puppet) ou l’OpenTelemetry Operator dans des environnements Kubernetes. Consultez Envoyer des données OpenTelemetry pour la configuration de production.
Dernière modification le 25 juin 2026