Surveillance et alertes de production avec Docker Compose : guide pas à pas

Introduction

Lorsque vous exécutez des charges de travail en production avec Docker Compose, la surveillance et les alertes sont essentielles pour maintenir la santé des services, détecter les problèmes rapidement et réagir promptement. Contrairement aux plateformes de conteneurs gérées, un déploiement basé sur Compose impose souvent à votre équipe la responsabilité de l'observabilité. Ce guide vous propose une approche pratique, étape par étape, pour mettre en place la surveillance et les alertes d'une pile de production Docker Compose à l'aide d'outils open source largement disponibles.

Vous apprendrez ce qu'il faut surveiller, quelles métriques sont importantes, comment configurer les règles d'alerte, comment examiner les signaux des journaux, comment construire un tableau de bord de base et comment gérer les incidents. Chaque étape comprend des commandes concrètes, des extraits de configuration et des résultats attendus afin que vous puissiez implémenter et vérifier chaque élément.

Une approche structurée de la surveillance et des alertes réduit les retouches en séparant la recherche, le cahier des charges, la génération, l'évaluation, l'approbation et la publication. Cet article suit ce principe : nous commençons par un inventaire, puis nous configurons, vérifions et planifions la récupération. Un projet pilote de surveillance clair doit être étroit, mesurable et facile à inspecter localement avant le déploiement ; ici, nous commençons par une configuration minimale mais complète.

Inventaire des versions et de l'environnement

Avant d'ajouter la surveillance, documentez précisément votre environnement. Cela évite les incompatibilités de versions et facilite le dépannage.

Prérequis

• Un serveur Linux (ou une machine virtuelle) exécutant Docker Engine 20.10+ et Docker Compose v2.0+.
• Accès au serveur via SSH avec des privilèges sudo.
• Une application Docker Compose en cours d'exécution. Pour ce guide, nous supposons une application web simple avec une base de données, mais les étapes se généralisent.
• Une familiarité de base avec la ligne de commande et YAML.

Récupérer les versions

Exécutez les commandes suivantes pour confirmer votre configuration :

docker --version
# Docker version 24.0.7, build afdd53b

docker compose version
# Docker Compose version v2.23.0

Définir la topologie de votre pile

Listez vos services Compose existants et leurs configurations. Par exemple :

# docker-compose.yml
version: '3.8'
services:
  web:
    image: nginx:1.25
    ports:
      - "80:80"
    depends_on:
      - app
  app:
    build: ./app
    environment:
      DB_HOST: db
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - dbdata:/var/lib/postgresql/data
volumes:
  dbdata:

Cette pile d'exemple comporte trois services : web (proxy inverse nginx), app (application personnalisée) et db (PostgreSQL). Votre pile peut différer, mais identifiez les composants qui nécessitent une surveillance.

Inventorier les ports exposés et les dépendances

Documentez quels ports sont exposés et quels services dépendent les uns des autres. Cela vous aide à savoir quoi surveiller et à éviter les conflits de ports lors de l'ajout d'exportateurs de surveillance.

Chemin de configuration sûr

Nous allons mettre en place la surveillance sans modifier vos services existants, en utilisant une pile de surveillance distincte. Cela laisse les services de production intacts et réduit les risques. Nous utiliserons Prometheus pour la collecte de métriques, Alertmanager pour le routage des alertes, Node Exporter et cAdvisor pour les métriques de l'hôte et des conteneurs, et Grafana pour les tableaux de bord.

Ajouter les services de surveillance à votre fichier Compose

Créez un fichier monitoring-compose.yml séparé pour éviter de modifier votre fichier de production. Ce fichier définit les services de surveillance et les attache au même réseau que votre application.

Tout d'abord, créez un réseau Docker externe pour que les deux piles puissent communiquer :

docker network create monitoring

Ensuite, créez monitoring-compose.yml :

version: '3.8'
services:
  prometheus:
    image: prom/prometheus:v2.48.0
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
    ports:
      - "9090:9090"
    networks:
      - monitoring

  alertmanager:
    image: prom/alertmanager:v0.26.0
    volumes:
      - ./alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml
    ports:
      - "9093:9093"
    networks:
      - monitoring

  node-exporter:
    image: prom/node-exporter:v1.7.0
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
    command:
      - '--path.procfs=/host/proc'
      - '--path.sysfs=/host/sys'
      - '--path.rootfs=/rootfs'
    ports:
      - "9100:9100"
    networks:
      - monitoring

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:v0.47.0
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    ports:
      - "8080:8080"
    networks:
      - monitoring

  grafana:
    image: grafana/grafana:10.2.1
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - monitoring

volumes:
  prometheus_data:
  grafana_data:

networks:
  monitoring:
    external: true

Cette configuration démarre Prometheus sur le port 9090, Alertmanager sur 9093, Node Exporter sur 9100, cAdvisor sur 8080 et Grafana sur 3000. Ils rejoignent tous le réseau externe de surveillance.

Configurer Prometheus

Prometheus a besoin d'un fichier de configuration pour collecter les métriques des exportateurs et de vos services d'application.

Créez prometheus/prometheus.yml :

global:
  scrape_interval: 15s
  evaluation_interval: 15s

alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - alertmanager:9093

rule_files:
  - "alerts.yml"

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

  - job_name: 'node'
    static_configs:
      - targets: ['node-exporter:9100']

  - job_name: 'cadvisor'
    static_configs:
      - targets: ['cadvisor:8080']

  # Ajoutez vos services d'application s'ils exposent /metrics
  # - job_name: 'web'
  #   static_configs:
  #     - targets: ['web:80']

Si votre application expose des métriques Prometheus, ajoutez une configuration de collecte pour elle. Sinon, nous nous appuierons sur cAdvisor pour les métriques au niveau des conteneurs.

Définir les règles d'alerte

Créez prometheus/alerts.yml avec des règles pour les conditions de défaillance courantes :

groups:
  - name: docker_compose_alerts
    rules:
      - alert: ContainerDown
        expr: absent(container_last_seen{name=~".+"})
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Conteneur arrêté (instance {{ $labels.instance }})"
          description: "Un conteneur est arrêté depuis plus de 1 minute."

      - alert: HighCPUUsage
        expr: sum(rate(container_cpu_usage_seconds_total{name=~".+"}[5m])) by (name) > 0.8
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Utilisation CPU élevée (conteneur {{ $labels.name }})"
          description: "L'utilisation CPU du conteneur est supérieure à 80% pendant 5 minutes."

      - alert: HighMemoryUsage
        expr: container_memory_usage_bytes{name=~".+"} / container_spec_memory_limit_bytes{name=~".+"} > 0.9
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Utilisation mémoire élevée (conteneur {{ $labels.name }})"
          description: "L'utilisation mémoire du conteneur est supérieure à 90% de sa limite pendant 5 minutes."

Ces règles alertent si un conteneur disparaît, si l'utilisation CPU dépasse 80 % ou si l'utilisation mémoire dépasse 90 % de sa limite.

Configurer Alertmanager

Créez alertmanager/alertmanager.yml :

route:
  receiver: 'default'
receivers:
  - name: 'default'
    email_configs:
      - to: '[email protected]'
        from: '[email protected]'
        smarthost: 'smtp.example.com:587'
        auth_username: '[email protected]'
        auth_password: 'password'

Remplacez les paramètres de messagerie par les vôtres. Pour d'autres canaux de notification (Slack, PagerDuty, etc.), reportez-vous à la documentation d'Alertmanager.

Démarrer la pile de surveillance

Démarrez les services de surveillance :

docker compose -f monitoring-compose.yml up -d

Vérifiez que tous les conteneurs sont en cours d'exécution :

docker compose -f monitoring-compose.yml ps

La sortie attendue montre tous les services avec l'état « Up ».

Vérification et diagnostics

Nous allons maintenant vérifier que chaque composant de surveillance fonctionne correctement.

Vérifier les cibles Prometheus

Ouvrez l'interface web de Prometheus à l'adresse http://<server-ip>:9090/targets. Toutes les cibles doivent afficher « UP » (vert). Vous pouvez également utiliser l'API :

curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, health: .health}'

Exemple de sortie :

{"job":"prometheus","health":"up"}
{"job":"node","health":"up"}
{"job":"cadvisor","health":"up"}

Si une cible est hors service, vérifiez le message d'erreur dans l'interface et contrôlez la connectivité réseau et les noms de service.

Vérifier les règles d'alerte

Dans l'interface de Prometheus, allez dans « Alerts ». Vous devriez voir les trois alertes que nous avons définies. Elles peuvent être initialement à l'état « inactive ». Vous pouvez tester en arrêtant temporairement un conteneur :

docker stop <container_name>

Après 1 minute, l'alerte ContainerDown devrait se déclencher (état « pending » puis « firing »). Redémarrez le conteneur après le test.

Vérifier les métriques cAdvisor

cAdvisor expose les métriques des conteneurs. Interrogez une métrique exemple :

curl -s 'http://localhost:8080/metrics' | grep 'container_cpu_usage_seconds_total'

Vous devriez voir des métriques avec les noms des conteneurs.

Vérifier les métriques Node Exporter

De même, vérifiez les métriques de l'hôte :

curl -s 'http://localhost:9100/metrics' | grep 'node_cpu_seconds_total'

Tester Alertmanager

Déclenchez une alerte de test en utilisant l'API d'Alertmanager ou en arrêtant temporairement un service. Consultez l'interface d'Alertmanager à l'adresse http://<server-ip>:9093 pour voir les alertes. Si la messagerie est configurée, vous devriez recevoir une notification (vérifiez votre boîte mail).

Configurer un tableau de bord Grafana

Accédez à Grafana à l'adresse http://<server-ip>:3000 (identifiants par défaut admin/admin).

• Ajoutez Prometheus comme source de données :
• Allez dans Configuration > Data Sources > Add data source > Prometheus.
• Définissez l'URL sur http://prometheus:9090 (puisque Grafana est sur le même réseau Docker).
• Cliquez sur « Save & Test ».

• Importez un tableau de bord de surveillance Docker :
• Allez dans Dashboards > Import.
• Saisissez l'ID de tableau de bord 193 pour un tableau de bord de surveillance Docker populaire, ou utilisez l'ID 14282 pour un plus complet.
• Sélectionnez la source de données Prometheus et importez.

• Vérifiez que les panneaux affichent des données (CPU, mémoire, réseau, etc.). Si certains panneaux sont vides, assurez-vous que vos requêtes Prometheus correspondent aux métriques disponibles (les différences de version de cAdvisor peuvent nécessiter des ajustements).

Inspecter les journaux pour détecter des signaux

Les journaux des conteneurs sont essentiels pour le débogage. Utilisez les pilotes de journalisation de Docker et un agrégateur de journaux si nécessaire. Pour des vérifications rapides :

docker logs <container_name> --tail 50

En production, envisagez d'utiliser le pilote de journalisation json-file et d'expédier les journaux vers un système central comme Loki ou ELK. Docker Compose peut configurer la journalisation par service :

services:
  web:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Ensuite, utilisez un outil de traitement des journaux pour détecter des motifs et alerter en conséquence.

Modes de défaillance et récupération

La surveillance elle-même peut échouer ou produire de fausses alarmes. Préparez-vous aux problèmes courants.

Perte de données Prometheus

Si les données de Prometheus sont perdues (par exemple, volume supprimé), vous perdez les métriques historiques mais la surveillance peut redémarrer. Pour atténuer cela, sauvegardez régulièrement le volume de données Prometheus ou utilisez un stockage distant. Pour simplifier, assurez-vous que le volume prometheus_data est inclus dans votre stratégie de sauvegarde.

Tempêtes d'alertes

Trop d'alertes peuvent submerger. Utilisez le regroupement d'alertes et les règles d'inhibition dans Alertmanager. Par exemple, regroupez les alertes par service et environnement pour réduire le bruit. Définissez également des durées for appropriées pour éviter le battement.

Faux positifs

Si une alerte se déclenche mais que le service est sain, ajustez les seuils. Par exemple, l'utilisation de la mémoire peut augmenter pendant le fonctionnement normal ; augmentez le seuil ou la durée. Utilisez Grafana pour observer les tendances et affiner.

Indisponibilité de la pile de surveillance

Si Prometheus ou Alertmanager tombe en panne, vous risquez de manquer des alertes. Envisagez de les exécuter dans une configuration haute disponibilité ou utilisez un service de surveillance externe de la disponibilité (comme UptimeRobot) pour interroger vos points de terminaison de surveillance.

Plan de retour en arrière

Si la configuration de surveillance cause des problèmes, vous pouvez arrêter la pile de surveillance sans affecter votre application :

docker compose -f monitoring-compose.yml down

Cela supprime les conteneurs de surveillance mais laisse les volumes intacts. Pour supprimer également les volumes (perte de données), ajoutez le drapeau -v.

Vérifications de récupération

Après tout changement ou récupération, refaites les étapes de vérification pour vous assurer que toutes les cibles sont opérationnelles et que les alertes fonctionnent.

Pièges courants et comment les éviter

La mise en place de la surveillance pour Docker Compose comporte plusieurs erreurs récurrentes. Voici les plus fréquentes et comment les prévenir ou les corriger.

Coder en dur les noms de conteneurs dans les règles d'alerte

Pourquoi cela arrive : Les développeurs copient souvent des expressions d'alerte qui référencent des noms de conteneurs spécifiques, comme container_memory_usage_bytes{name="web"}. Lorsque les conteneurs sont recréés ou mis à l'échelle, les noms changent et les alertes échouent silencieusement.

Comment éviter : Utilisez des correspondances d'étiquettes stables, comme image, com.docker.compose.service ou com.docker.compose.project. Par exemple, au lieu de name="web", utilisez com.docker.compose.service="web". Si vous devez utiliser des noms, utilisez une expression régulière comme name=~"web.*" pour capturer les suffixes.

Récupération : Si les alertes cessent de se déclencher, examinez la métrique container_last_seen dans Prometheus pour voir les étiquettes actuelles. Mettez à jour vos expressions d'alerte en conséquence.

Utiliser le même réseau que la production sans isolation

Pourquoi cela arrive : Les équipes peuvent ajouter des services de surveillance directement au fichier Compose de production pour simplifier. Cela couple la pile de surveillance à la production et peut provoquer des conflits de ports ou des modifications accidentelles de la configuration.

Comment éviter : Gardez la surveillance dans un fichier Compose séparé et utilisez un réseau externe. Ainsi, vous pouvez redémarrer ou mettre à jour la surveillance sans toucher à la production. Comme indiqué précédemment, créez le réseau avec docker network create monitoring et attachez-y les deux piles.

Récupération : Si vous les avez déjà mélangés, extrayez les services de surveillance dans leur propre fichier, créez le réseau et redéployez. Testez d'abord dans un environnement de préproduction.

Ignorer la croissance du stockage

Pourquoi cela arrive : Prometheus stocke des données de séries temporelles, qui peuvent croître indéfiniment. Sans limites de rétention, le disque se remplit, ce qui entraîne le crash de Prometheus ou l'arrêt de l'ingestion de données.

Comment éviter : Définissez une période ou une limite de taille de rétention dans la commande Prometheus. Par exemple, ajoutez --storage.tsdb.retention.time=15d pour conserver 15 jours de données. Surveillez l'utilisation du disque avec une alerte distincte.

Récupération : Si le disque est plein, arrêtez Prometheus, supprimez manuellement les anciens blocs de données (ou supprimez le volume), puis redémarrez avec les paramètres de rétention appropriés. Assurez-vous d'avoir une sauvegarde si les données historiques sont nécessaires.

Ne pas tester les alertes de bout en bout

Pourquoi cela arrive : Les équipes configurent les alertes et supposent qu'elles fonctionnent, mais les notifications peuvent être mal acheminées ou bloquées par les filtres de messagerie.

Comment éviter : Déclenchez régulièrement une alerte de test (par exemple, arrêtez un conteneur de test) et vérifiez que la notification atteint le canal prévu. Incluez cela dans votre liste de contrôle opérationnelle.

Récupération : Si une alerte ne s'est pas déclenchée, vérifiez les journaux d'Alertmanager et l'état de livraison du fournisseur de notification. Ajustez le routage ou les identifiants.

Suralerte et fatigue liée aux alertes

Pourquoi cela arrive : Des règles d'alerte avec des seuils bas ou des durées for courtes génèrent trop d'alertes, ce qui amène les équipes à les ignorer.

Comment éviter : Commencez par des seuils prudents et des durées plus longues. Utilisez Grafana pour observer le comportement normal pendant une semaine, puis ajustez. Regroupez les alertes et utilisez des niveaux de gravité pour hiérarchiser.

Récupération : Si vous souffrez déjà de fatigue liée aux alertes, examinez les alertes récentes dans Alertmanager, identifiez les plus bruyantes et ajustez-les. Supprimez ou mettez en pause les alertes qui ne sont pas actionnables.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour les opérations courantes. Attribuez un responsable unique pour chaque domaine et définissez une fréquence de révision.

Effectuez ces vérifications régulièrement et après tout changement. Le responsable est chargé de la vérification, et la fréquence de révision indique à quelle fréquence le résultat doit être réexaminé.

Conclusion

Vous disposez maintenant d'une configuration complète de surveillance et d'alerte pour votre déploiement de production Docker Compose. Vous avez commencé par un inventaire de l'environnement, ajouté une pile de surveillance distincte avec Prometheus, Alertmanager, Node Exporter, cAdvisor et Grafana, défini des règles d'alerte, vérifié chaque composant et préparé des procédures de récupération.

Prochaines étapes :

• Personnalisez les règles d'alerte pour les métriques spécifiques à votre application.
• Ajoutez d'autres tableaux de bord pour vos services.
• Mettez en place un système d'agrégation de journaux et intégrez-le à Alertmanager.
• Testez votre processus de réponse aux incidents avec un exercice d'incendie.
• Révisez et mettez à jour régulièrement les seuils en fonction des schémas observés.

Un projet pilote de surveillance clair doit être étroit, mesurable et facile à inspecter localement avant le déploiement. Commencez par les bases, faites-les fonctionner de manière fiable, puis étendez. La surveillance est une discipline continue, pas une configuration ponctuelle.