> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Surveillance des logs AWS CloudWatch avec ClickStack
> Surveillance des logs AWS CloudWatch avec ClickStack
export const TrackedLink = ({href, eventName, children, ...rest}) => {
const handleClick = () => {
try {
if (typeof window !== "undefined" && window.galaxy && eventName) {
window.galaxy.track(eventName, {
interaction: "click"
});
}
} catch (e) {}
};
return
{children}
;
};
export const Image = ({img, alt, size}) => {
return
;
};
**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](#demo-dataset).
### 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.
#### 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](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 :
```bash theme={null}
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) :**
```bash theme={null}
# 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 :**
```bash theme={null}
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 :
```json theme={null}
{
"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.
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) :
```bash theme={null}
aws logs describe-log-groups --region us-east-1 \
--query 'logGroups[].logGroupName' --output table
```
Exemple de sortie :
```text theme={null}
-------------------------------
| 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 :
```yaml theme={null}
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 :
```yaml theme={null}
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` :
```yaml theme={null}
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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver).
**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.
#### Démarrer le collector
Créez un fichier `docker-compose.yaml` :
```yaml theme={null}
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 :
```bash theme={null}
docker compose up -d
```
Consultez les logs du collector :
```bash theme={null}
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](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.
#### Télécharger le jeu de données d’exemple
```bash theme={null}
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 :
```bash theme={null}
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
```bash theme={null}
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](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.
#### Télécharger la 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 :
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 :**
```bash theme={null}
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 :**
```bash theme={null}
# 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 :**
```bash theme={null}
# 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 :
```bash theme={null}
# Stop the collector
docker stop
# 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 :**
```bash theme={null}
# 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
```
### 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 :
```yaml theme={null}
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 :**
```yaml theme={null}
processors:
batch:
timeout: 5s
send_batch_size: 100
```
**Limiter la découverte automatique :**
```yaml theme={null}
groups:
autodiscover:
limit: 50 # Reduce from 100 to 50
```
## Étapes suivantes
* Configurez des [alertes](/fr/clickstack/features/alerts) 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](/fr/clickstack/ingesting-data/opentelemetry) pour découvrir des modèles de déploiement en production et des exemples de configuration du collecteur.