Supervision des logs d’hôte EC2 avec ClickStack

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

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

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

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

sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
receivers:
  filelog/syslog:
    include:
      - /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: "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

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

Démarrez l’OpenTelemetry Collector :

CLICKSTACK_API_KEY="your-api-key-here" /usr/local/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml

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

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

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

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

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

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

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

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

3. Téléversez le fichier host-logs-dashboard.json et cliquez sur Terminer l’import

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