Surveillance des logs AWS CloudWatch avec ClickStack

Surveillance des logs AWS CloudWatch avec ClickStack

En bref

Transférez les logs AWS CloudWatch vers ClickStack à l’aide du receiver CloudWatch de l’OpenTelemetry Collector. Prend en charge les groupes de logs nommés et l’autodécouverte. Inclut un jeu de données de démonstration et un tableau de bord préconfiguré.

​

Vue d’ensemble

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.

​

Intégration avec des CloudWatch log groups existants

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.

​

Prérequis

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

Contrairement aux intégrations de logs basées sur des fichiers (nginx, Redis), CloudWatch nécessite l’exécution d’un OpenTelemetry Collector distinct qui interroge l’API CloudWatch. Ce collecteur ne peut pas s’exécuter dans l’image tout-en-un de ClickStack, car il nécessite des identifiants AWS et un accès à l’API.

1. ​

   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"
   
2. ​

   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.

3. ​

   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

   Le CloudWatch receiver ne récupère les logs que sur des fenêtres de temps récentes (en fonction de poll_interval). Lors du premier démarrage, il commence à l’heure actuelle. Les logs historiques ne sont pas récupérés par défaut.

4. ​

   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
   
5. ​

   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

​

Jeu de données de démonstration

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.

1. ​

   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
2. ​

   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.

3. ​

   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.

4. ​

   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.

   Affichage du fuseau horaire

   HyperDX affiche les timestamps selon le fuseau horaire local de votre navigateur. Les données de démonstration couvrent 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC). Définissez votre intervalle de temps sur 2025-12-06 00:00:00 - 2025-12-09 00:00:00 pour être sûr de voir les logs de démonstration, quel que soit votre emplacement. Une fois les logs affichés, vous pourrez réduire l’intervalle à 24 heures pour obtenir des visualisations plus claires.

​

Tableaux de bord et visualisations

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

1. ​

   la configuration du tableau de bord

2. ​

   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
3. ​

   Afficher le tableau de bord

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

   Pour le jeu de données de démonstration, définissez la plage horaire sur 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC) (à ajuster selon votre fuseau horaire local). Par défaut, aucune plage horaire n’est définie dans le tableau de bord importé.

​

Dépannage

​

Aucun log ne s’affiche dans HyperDX

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

​

Vous ne voyez que d’anciens logs ou il manque des logs récents

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.

​

Jeton de sécurité invalide / identifiants expirés

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>

​

Latence élevée ou absence de logs récents

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.

​

Collector utilisant trop de mémoire

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

​

Étapes suivantes

• 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

​

Mise en production

Ce guide explique comment exécuter l’OpenTelemetry Collector localement avec Docker Compose pour effectuer des tests. 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 logs CloudWatch pour 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.