Surveillance des logs AWS CloudWatch avec ClickStack

AWS CloudWatch est un service de surveillance des ressources et applications AWS. Bien que CloudWatch permette d’agréger les logs, les transférer vers ClickStack vous permet de :

• Analyser les logs avec les métriques et les traces sur une plateforme unifiée
• Interroger les logs via l’interface SQL de ClickHouse
• Réduire les coûts en archivant les logs ou en diminuant la durée de rétention dans CloudWatch

Ce guide explique comment transférer des logs CloudWatch vers ClickStack à l’aide de l’OpenTelemetry Collector.

Cette section explique comment configurer l’OpenTelemetry Collector pour collecter les logs de vos CloudWatch log groups existants et les transférer vers ClickStack.

Si vous souhaitez tester l’intégration avant de configurer votre environnement de production, vous pouvez utiliser notre jeu de données de démonstration dans la section consacrée au jeu de données de démonstration.

• Instance ClickStack en cours d’exécution
• Compte AWS avec des groupes de journaux CloudWatch
• Identifiants AWS disposant des autorisations IAM appropriées

Obtenir une API key ClickStack

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

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

Enregistrez-la dans une variable d’environnement :

export CLICKSTACK_API_KEY="your-api-key-here"

Configurer les identifiants AWS

Exportez vos identifiants AWS sous forme de variables d’environnement. La méthode dépend de votre type d’authentification :

Pour les utilisateurs d’AWS SSO (recommandé pour la plupart des organisations) :

# Login to SSO
aws sso login --profile YOUR_PROFILE_NAME

# Export credentials to environment variables
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# Verify credentials work
aws sts get-caller-identity

Remplacez YOUR_PROFILE_NAME par le nom de votre profil AWS SSO (par exemple, AccountAdministrators-123456789).

Pour les utilisateurs IAM disposant d’identifiants de longue durée :

export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export AWS_REGION="us-east-1"

# Verify credentials work
aws sts get-caller-identity

Autorisations IAM requises :

Le compte AWS associé à ces données d’authentification doit disposer de la stratégie IAM suivante pour lire les logs CloudWatch :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudWatchLogsRead",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:FilterLogEvents"
      ],
      "Resource": "arn:aws:logs:*:YOUR_ACCOUNT_ID:log-group:*"
    }
  ]
}

Remplacez YOUR_ACCOUNT_ID par l’identifiant de votre compte AWS.

Configurer le CloudWatch receiver

Créez un fichier otel-collector-config.yaml avec la configuration du CloudWatch receiver.

Découvrir les groupes de logs disponibles dans votre compte

Avant de modifier la configuration, listez les groupes de logs présents dans votre région afin de pouvoir choisir de vrais noms (et confirmer que la région est correcte) :

aws logs describe-log-groups --region us-east-1 \
  --query 'logGroups[].logGroupName' --output table

Exemple de sortie :

-------------------------------
|      DescribeLogGroups      |
+-----------------------------+
|  /aws-glue/jobs/error       |
|  /aws-glue/jobs/logs-v2     |
|  /aws-glue/jobs/output      |
|  /aws-glue/sessions/error   |
|  /aws-glue/sessions/output  |
+-----------------------------+

Utilisez directement les noms de cette liste dans le bloc groups.named de l’exemple 1 ci-dessous. Pour le compte ci-dessus, la section named-groups deviendrait :

groups:
  named:
    /aws-glue/jobs/error:
    /aws-glue/jobs/logs-v2:
    /aws-glue/jobs/output:
    /aws-glue/sessions/error:
    /aws-glue/sessions/output:

Sinon, si les groupes souhaités partagent un préfixe commun (ici /aws-glue/), utilisez l’exemple 2 avec prefix: /aws-glue/ au lieu de les lister individuellement.

Exemple 1 : groupes de logs nommés (recommandé)

Cette configuration collecte les logs de groupes de logs nommés spécifiques :

receivers:
  awscloudwatch:
    region: us-east-1
    logs:
      poll_interval: 1m
      max_events_per_request: 100
      groups:
        named:
          /aws/lambda/my-function:
          /aws/ecs/my-service:
          /aws/eks/my-cluster/cluster:

processors:
  batch:
    timeout: 10s

exporters:
  otlphttp:
    endpoint: http://localhost:4318
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [awscloudwatch]
      processors: [batch]
      exporters: [otlphttp]

Exemple 2 : Découverte automatique des groupes de logs par préfixe

Cette configuration découvre automatiquement et collecte les logs d’un maximum de 100 groupes de logs dont le nom commence par le préfixe /aws/lambda :

receivers:
  awscloudwatch:
    region: us-east-1
    logs:
      poll_interval: 1m
      max_events_per_request: 100
      groups:
        autodiscover:
          limit: 100
          prefix: /aws/lambda

processors:
  batch:
    timeout: 10s

exporters:
  otlphttp:
    endpoint: http://localhost:4318
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [awscloudwatch]
      processors: [batch]
      exporters: [otlphttp]

Paramètres de configuration :

• region : région AWS où se trouvent vos groupes de logs
• poll_interval : fréquence de vérification des nouveaux logs (par ex. : 1m, 5m)
• max_events_per_request : nombre maximal d’événements de log à récupérer par requête
• groups.autodiscover.limit : nombre maximal de groupes de logs à découvrir
• groups.autodiscover.prefix : filtrer les groupes de logs par préfixe
• groups.named : lister explicitement les noms des groupes de logs à collecter

Pour plus d’options de configuration, consultez la documentation du CloudWatch receiver.

Remplacez les éléments suivants :

• ${CLICKSTACK_API_KEY} → utilise la variable d’environnement que vous avez définie précédemment
• http://localhost:4318 → votre endpoint ClickStack (utilisez votre hôte ClickStack si vous l’exécutez à distance)
• us-east-1 → votre région AWS
• Noms/préfixes des groupes de logs → vos groupes de logs CloudWatch réels

Démarrer le collector

Créez un fichier docker-compose.yaml :

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel-config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-config.yaml
    environment:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - AWS_SESSION_TOKEN
      - AWS_REGION
      - CLICKSTACK_API_KEY
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"

Ensuite, démarrez le collecteur :

docker compose up -d

Consultez les logs du collector :

docker compose logs -f otel-collector

Vérifier les logs dans HyperDX

Une fois le collector en cours d’exécution :

1. Ouvrez HyperDX à l’adresse http://localhost:8080 (ou à l’URL de votre instance ClickStack)
2. Accédez à la vue Logs
3. Attendez 1 à 2 minutes que les logs s’affichent (selon votre intervalle d’interrogation)
4. Recherchez les logs provenant de vos groupes de logs CloudWatch

Repérez les attributs clés suivants dans les logs :

• ResourceAttributes['aws.region'] : votre région AWS (par ex. : "us-east-1")
• ResourceAttributes['cloudwatch.log.group.name'] : le nom du groupe de logs CloudWatch
• ResourceAttributes['cloudwatch.log.stream'] : le nom du flux de logs
• Body : le contenu réel du message de log

Pour les utilisateurs qui souhaitent tester l’intégration CloudWatch Logs avant de configurer leur environnement AWS de production, nous fournissons un jeu de données d’exemple contenant des logs pré-générés qui reproduisent des schémas réalistes issus de plusieurs services AWS.

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

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/aws/cloudwatch/cloudwatch-logs.jsonl

Le jeu de données contient 24 heures de logs CloudWatch provenant de plusieurs services :

• Fonctions Lambda : traitement des paiements, gestion des commandes, authentification
• Services ECS : passerelle d’API avec limitation de débit et délais d’expiration
• Tâches en arrière-plan : traitement par lots avec mécanismes de nouvelle tentative

Démarrer ClickStack

Si ClickStack n’est pas déjà en cours d’exécution :

docker run -d --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

Patientez quelques instants, le temps que ClickStack démarre complètement.

Importer le jeu de données de démonstration

docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_logs FORMAT JSONEachRow
" < cloudwatch-logs.jsonl

Cette commande importe directement les logs dans la table de logs de ClickStack.

Vérifier les données de démonstration

Une fois l’import terminé :

1. Ouvrez HyperDX à l’adresse http://localhost:8080 et connectez-vous (créez un compte si nécessaire)
2. Accédez à la vue Logs
3. Définissez l’intervalle de temps sur 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC)
4. Recherchez cloudwatch-demo ou appliquez le filtre LogAttributes['source'] = 'cloudwatch-demo'

Vous devriez voir des logs provenant de plusieurs groupes de logs CloudWatch.

Pour vous aider à surveiller les logs CloudWatch Logs avec ClickStack, nous fournissons un tableau de bord prêt à l’emploi avec les visualisations essentielles.

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

1. Ouvrez HyperDX et accédez à la section Dashboards
2. Cliquez sur Import Dashboard dans le coin supérieur droit, sous le menu à points de suspension

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

Afficher le tableau de bord

Le tableau de bord sera créé avec toutes les visualisations déjà configurées :

Vérifiez que les identifiants AWS sont configurés :

aws sts get-caller-identity

Si cela échoue, vos identifiants ne sont pas valides ou ont expiré.

Vérifiez les autorisations IAM : Assurez-vous que vos identifiants AWS disposent des autorisations requises logs:DescribeLogGroups et logs:FilterLogEvents.

Vérifiez les logs du collector pour repérer d’éventuelles erreurs :

# If using Docker directly, logs appear in stdout
# If using Docker Compose:
docker compose logs otel-collector

Erreurs courantes :

• The security token included in the request is invalid : les identifiants sont invalides ou ont expiré. Pour les identifiants temporaires (SSO), assurez-vous que AWS_SESSION_TOKEN est défini.
• operation error CloudWatch Logs: FilterLogEvents, AccessDeniedException : les permissions IAM sont insuffisantes
• failed to refresh cached credentials, no EC2 IMDS role found : les variables d’environnement des identifiants AWS ne sont pas définies
• connection refused : l’endpoint ClickStack est inaccessible

Vérifiez que les groupes de logs CloudWatch existent et contiennent des logs récents :

# List your log groups
aws logs describe-log-groups --region us-east-1

# Check if a specific log group has recent logs (last hour)
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --region us-east-1 \
  --start-time $(date -u -v-1H +%s)000 \
  --max-items 5

Le receiver CloudWatch démarre à partir de "maintenant" par défaut :

Lorsque le collector démarre pour la première fois, il crée un point de contrôle à l’heure actuelle et ne récupère que les logs postérieurs à ce point. Les logs historiques ne sont pas récupérés.

Pour collecter des logs historiques récents :

Arrêtez et supprimez le point de contrôle du collector, puis redémarrez :

# Stop the collector
docker stop <container-id>

# Restart fresh (checkpoints are stored in container, so removing it resets)
docker run --rm ...

Le receiver créera un nouveau point de contrôle et récupérera les logs à partir de maintenant.

Si vous utilisez des identifiants temporaires (AWS SSO, rôle assumé), ils expirent au bout d’un certain temps.

Réexportez des identifiants à jour :

# For SSO users:
aws sso login --profile YOUR_PROFILE_NAME
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# For IAM users:
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

# Restart the collector
docker restart <container-id>

Réduire l’intervalle d’interrogation : La valeur par défaut de poll_interval est de 1 minute. Pour obtenir des logs en temps quasi réel, réduisez-la :

logs:
  poll_interval: 30s  # Poll every 30 seconds

Remarque : Des intervalles de scrutation plus courts augmentent le nombre d’appels à l’API AWS et peuvent entraîner des coûts plus élevés pour l’API CloudWatch.

Réduisez la taille du batch ou augmentez le délai d’expiration :

processors:
  batch:
    timeout: 5s
    send_batch_size: 100

Limiter la découverte automatique :

groups:
  autodiscover:
    limit: 50  # Reduce from 100 to 50

• Configurez des alertes pour les événements critiques (échecs de connexion, pics d’erreurs)
• Réduisez les coûts de CloudWatch en ajustant les durées de rétention ou en archivant les données dans S3, maintenant que vous avez les logs dans ClickStack
• Filtrez les groupes de logs trop bruyants en les supprimant de la configuration du collector afin de réduire le volume d’ingestion

Ce guide montre comment exécuter l’OpenTelemetry Collector localement avec Docker Compose à des fins de test. Pour les déploiements en production, exécutez le collecteur sur une infrastructure disposant d’un accès AWS (EC2 avec des rôles IAM, EKS avec IRSA ou ECS avec des rôles de tâche) afin d’éviter d’avoir à gérer des clés d’accès. Déployez les collecteurs dans la même région AWS que vos groupes de journaux CloudWatch afin de réduire la latence et les coûts.

Consultez Ingestion avec OpenTelemetry pour découvrir des modèles de déploiement en production et des exemples de configuration du collecteur.