Surveillance et alertes du cache de build Docker : guide pratique de mise en œuvre

Introduction

Le cache de build Docker est l'un des outils les plus puissants pour accélérer la construction d'images et optimiser les pipelines CI/CD. Il stocke les couches intermédiaires et les réutilise lorsque les instructions et le contexte de build n'ont pas changé. Lorsque le cache fonctionne bien, des builds qui prenaient des minutes peuvent tomber à quelques secondes. Mais lorsque le cache se comporte de manière inattendue, les développeurs font face à des builds lents, une utilisation disque excessive et des images incohérentes difficiles à déboguer.

La surveillance et les alertes sur les performances du cache de build aident les équipes à détecter ces problèmes tôt, à réduire les frictions pour les développeurs et à maintenir des pipelines fiables. Sans visibilité, un problème de cache peut dégrader silencieusement les builds pendant des jours, gaspillant du temps de calcul et retardant les mises en production.

Ce guide explique quoi surveiller dans le cache de build Docker, les métriques clés à suivre, comment configurer des règles d'alerte et des tableaux de bord, et que faire en cas d'incident. Chaque étape majeure inclut des commandes concrètes, des extraits de configuration ou des exemples détaillés pour vous permettre d'implémenter la surveillance dans votre propre environnement.

Inventaire des versions et de l'environnement

Avant d'implémenter la surveillance du cache, établissez votre environnement et ses prérequis. Les différentes versions de Docker et BuildKit exposent des métriques et des comportements de cache différents, alors commencez par confirmer ce que vous exécutez.

Versions de Docker et BuildKit

Le comportement du cache de build Docker dépend de la version du moteur Docker et du backend de build. BuildKit, le builder par défaut pour Docker 23.0 et versions ultérieures, offre une mise en cache avancée et de meilleures performances. Vérifiez votre version de Docker avec :

docker version --format '{{.Server.Version}}'

Exemple de sortie :

24.0.5

Vérifiez que BuildKit est disponible et sa version :

docker buildx version

La sortie attendue inclut la version de buildx :

github.com/docker/buildx v0.11.2

Si vous utilisez une ancienne version de Docker, envisagez une mise à niveau. Les nouvelles versions incluent une meilleure gestion du cache, une intégration BuildKit améliorée et des endpoints de métriques plus fiables.

Topologie de l'environnement

Le cache est stocké localement sur chaque nœud de build. Dans une configuration de développement typique, cela signifie le portable du développeur ou un runner CI. Dans des configurations plus importantes, les équipes utilisent souvent un cache distant partagé, comme un registre de conteneurs avec prise en charge du cache ou un cache distribué comme le cache de registre de BuildKit. Les caches distants permettent à plusieurs machines de réutiliser les mêmes couches, ce qui est essentiel pour les runners CI mis à l'échelle horizontalement.

Pour ce guide, nous supposons un environnement local à nœud unique avec Docker Engine et BuildKit activés. Les exemples sont faciles à adapter pour les caches distants : il vous suffira d'ajouter des drapeaux d'importation et d'exportation de cache à vos commandes de build.

Prérequis

• Docker Engine 20.10 ou version ultérieure (pour la prise en charge de BuildKit).
• Accès en ligne de commande à l'environnement de build.
• Connaissance de base de Prometheus, Grafana ou de votre pile de surveillance.
• Optionnel : Node Exporter ou cAdvisor pour les métriques au niveau de l'hôte telles que l'utilisation du disque.

Chemin de configuration sûr

Commencez par un pilote étroit et mesurable. Surveillez les métriques de cache local sur un nœud de build avant de passer à des caches distants ou distribués. Cela réduit les risques et vous permet d'ajuster les alertes sans affecter l'ensemble de la flotte.

Activation des métriques BuildKit

BuildKit expose des métriques Prometheus via un endpoint HTTP lorsqu'il est exécuté en tant que démon autonome avec les bons drapeaux. Le BuildKit intégré à Docker n'expose pas directement les métriques, mais vous pouvez exécuter un démon BuildKit séparé pour la surveillance et les tests :

sudo buildkitd --addr unix:///run/buildkit/buildkitd.sock --debug --addr tcp://0.0.0.0:1234

Accédez ensuite aux métriques à l'adresse http://localhost:1234/metrics. C'est idéal pour comprendre les métriques disponibles avant de les intégrer à votre configuration de build en production.

Pour les builds Docker normaux utilisant le BuildKit par défaut, vous pouvez toujours obtenir une visibilité sur le cache à partir des journaux de build. Définissez la variable d'environnement BUILDKIT_PROGRESS=plain pour voir l'état du cache dans la sortie du journal, bien que ce ne soit pas des données de séries temporelles.

Instrumentation des commandes de build

Au lieu de métriques directes, vous pouvez ajouter une surveillance autour de vos commandes de build. Utilisez docker buildx build avec le drapeau --progress=plain pour capturer les succès et les échecs de cache dans la sortie du journal :

docker buildx build --progress=plain -t myapp:latest . 2>&1 | tee build.log

Analysez ensuite le journal pour les lignes qui indiquent les résultats du cache. Un succès de cache apparaît ainsi :

#12 [stage-1 2/4] COPY --from=builder /app /app
#12 CACHED

Un échec de cache ressemble à ceci :

#12 [stage-1 2/4] COPY --from=builder /app /app
#12 DONE 0.2s

Automatisez cette analyse avec un script ou un outil d'agrégation de journaux tel que Loki ou ELK. Vous pouvez ensuite créer des métriques et des alertes basées sur le taux de succès du cache dérivé des journaux.

Configuration de Prometheus et Grafana

Si vous exécutez BuildKit autonome, vous pouvez collecter ses métriques avec Prometheus. Ajoutez une configuration de collecte comme celle-ci :

scrape_configs:
  - job_name: 'buildkit'
    static_configs:
      - targets: ['localhost:1234']

Créez ensuite un tableau de bord Grafana pour visualiser les métriques liées au cache. Les métriques spécifiques et les panneaux du tableau de bord sont couverts dans la section suivante.

Vérification et diagnostics

Une fois la surveillance en place, vérifiez qu'elle capture les données attendues et se comporte correctement. Commencez par vérifier que l'endpoint des métriques répond et que Prometheus le collecte. Explorez ensuite les métriques clés et comment les transformer en tableaux de bord et alertes.

Métriques clés à surveiller

BuildKit expose une variété de métriques. Les plus pertinentes pour la surveillance du cache sont :

Les noms de métriques peuvent différer légèrement selon la version de BuildKit. Vérifiez toujours l'endpoint /metrics pour les noms exacts dans votre environnement. Vous pouvez l'interroger manuellement avec :

curl -s http://localhost:1234/metrics | grep buildkit_cache

Sortie attendue (tronquée) :

# HELP buildkit_cache_hits_total Total number of cache hits
# TYPE buildkit_cache_hits_total counter
buildkit_cache_hits_total 42
# HELP buildkit_cache_misses_total Total number of cache misses
# TYPE buildkit_cache_misses_total counter
buildkit_cache_misses_total 7

Calcul du taux de succès du cache

Une métrique dérivée utile est le taux de succès du cache, qui indique quelle fraction des consultations du cache ont abouti à des succès. La formule est :

taux_de_succès_du_cache = buildkit_cache_hits_total / (buildkit_cache_hits_total + buildkit_cache_misses_total)

Dans Prometheus, vous pouvez utiliser une requête PromQL dans Grafana :

sum(rate(buildkit_cache_hits_total[5m])) / (sum(rate(buildkit_cache_hits_total[5m])) + sum(rate(buildkit_cache_misses_total[5m])))

Cette expression donne la proportion de succès de cache sur les 5 dernières minutes. Un cache sain a généralement un taux de succès supérieur à 0,8, mais cela peut varier selon la charge de travail.

Exemple de tableau de bord

Créez un tableau de bord Grafana avec ces panneaux :

• Taux de succès du cache - Un graphique montrant le ratio au fil du temps. Utilisez l'expression PromQL ci-dessus.
• Succès vs échecs du cache - Un graphique empilé de rate(buildkit_cache_hits_total[5m]) et rate(buildkit_cache_misses_total[5m]) pour voir le volume de chacun.
• Taille du cache - Un graphique de buildkit_cache_usage_bytes pour suivre l'utilisation du disque.
• Importations/exportations de cache - Des graphiques des taux d'importation et d'exportation pour surveiller le trafic du cache distant.

Définissez un seuil sur le panneau du taux de succès pour mettre en évidence lorsque le ratio tombe en dessous de 0,8. Cela facilite la détection des problèmes en un coup d'œil.

Vérification basée sur les journaux

Si vous utilisez l'analyse des journaux, vérifiez que votre analyseur identifie correctement les succès et les échecs. Par exemple, un simple script AWK peut compter les lignes CACHED dans un journal de build :

grep -c 'CACHED' build.log

La sortie attendue est le nombre d'étapes mises en cache. Vous pouvez également extraire les échecs en comptant les lignes DONE qui ne sont pas CACHED, mais cela nécessite un peu plus de logique. Une approche plus robuste consiste à utiliser un outil comme Loki pour agréger les lignes de journal et calculer les ratios au fil du temps.

Modes de défaillance et récupération

La surveillance elle-même peut échouer ou produire de fausses alertes. Soyez prêt à gérer les problèmes courants liés au cache et à la collecte de métriques.

Modes de défaillance courants

• Invalidation du cache due à des modifications du Dockerfile : Modifier une instruction dans le Dockerfile invalide toutes les couches suivantes, provoquant des échecs de cache. C'est attendu et peut déclencher des alertes si les seuils sont trop sensibles.
• Épuisement de l'espace disque : Le cache de build peut devenir volumineux et remplir le disque, provoquant des échecs de build. Surveillez l'utilisation du disque et définissez une taille de cache maximale avec --max-cache-size dans BuildKit.
• Cache corrompu : Parfois, le cache peut être corrompu, provoquant des échecs inattendus ou des erreurs de build. Nettoyer le cache avec docker builder prune résout ce problème.
• Problèmes réseau avec le cache distant : Si vous utilisez un cache distant, la latence ou l'indisponibilité du réseau peut entraîner l'échec des importations et exportations de cache, apparaissant comme des échecs de cache.
• Échec de la collecte de métriques : L'endpoint des métriques peut être inaccessible en raison d'une mauvaise configuration réseau ou de BuildKit ne l'exposant pas. Cela entraîne l'absence de données et des alertes manquées.

Règles d'alerte

Définissez des règles d'alerte pour détecter les problèmes sans être trop bruyant. Exemple de règles d'alerte Prometheus :

groups:
  - name: docker_build_cache
    rules:
      - alert: LowCacheHitRatio
        expr: (sum(rate(buildkit_cache_hits_total[5m])) / (sum(rate(buildkit_cache_hits_total[5m])) + sum(rate(buildkit_cache_misses_total[5m])))) < 0.6
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Le taux de succès du cache de build est faible"
          description: "Le taux de succès du cache est inférieur à 0,6 depuis 10 minutes."
      - alert: CacheUsageHigh
        expr: buildkit_cache_usage_bytes > 50e9 # 50 Go, ajuster selon les besoins
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Utilisation élevée du cache de build"
          description: "La taille du cache dépasse 50 Go."

Ajustez les seuils en fonction de votre base de référence. Certaines équipes préfèrent alerter uniquement lorsque le taux de succès reste faible pendant une période plus longue pour éviter le bruit dû aux changements légitimes.

Récupération et retour en arrière

Lorsqu'une alerte se déclenche, suivez ces étapes :

• Enquêter sur le taux de succès du cache : Vérifiez les modifications récentes du Dockerfile et du contexte de build. Si le changement est légitime, ajustez les seuils ou mettez temporairement l'alerte en sourdine.
• Libérer de l'espace disque : Exécutez docker builder prune --filter 'until=24h' pour supprimer le cache inutilisé. Pour un nettoyage complet, utilisez docker builder prune -a avec prudence.
• Corriger la connectivité du cache distant : Assurez-vous que l'accès réseau et les informations d'identification sont valides. Testez avec un build simple qui utilise le cache distant.
• Redémarrer BuildKit si l'endpoint des métriques est en panne.
• Revenir en arrière sur les changements de surveillance : Si une nouvelle règle d'alerte provoque du bruit, annulez-la immédiatement et itérez sur les seuils.

Flux de travail de réponse aux incidents

Créez un manuel de procédures pour les incidents liés au cache. Incluez :

• Identification des symptômes : builds lents, taux élevé d'échecs de cache, disque plein.
• Atténuation immédiate : nettoyer le cache, désactiver temporairement le cache avec --no-cache, ou revenir au cache local.
• Analyse des causes profondes : examiner les modifications du Dockerfile, la taille du contexte de build, les performances du cache distant et les changements récents de l'environnement.
• Revue post-incident : mettre à jour les seuils, améliorer la couverture de surveillance et documenter les leçons apprises.

Attribuez un responsable unique pour la réponse aux incidents de cache. Par exemple, l'ingénieur plateforme de garde est responsable de l'atténuation et du diagnostic initial. Révisez le manuel trimestriellement ou après chaque incident majeur.

Pièges courants et comment les éviter

Même avec une surveillance en place, les équipes commettent des erreurs qui réduisent l'efficacité du cache ou créent une fatigue des alertes. Voici les pièges les plus courants et comment les éviter ou s'en remettre.

Piège 1 : Ignorer la taille du contexte de build

Pourquoi cela arrive : Les développeurs ajoutent de gros fichiers ou répertoires au contexte de build sans s'en rendre compte. Un contexte énorme peut ralentir les builds et provoquer des échecs de cache inutiles car le hachage du contexte change.

Comment l'éviter : Utilisez un fichier .dockerignore pour exclure les fichiers inutiles du contexte de build. Révisez-le régulièrement. Un bon .dockerignore peut améliorer considérablement les performances du cache. Par exemple :

.git
*.md
node_modules

Comment s'en remettre : Si vous découvrez un contexte gonflé, mettez à jour .dockerignore et nettoyez les anciennes entrées de cache avec docker builder prune.

Piège 2 : Trop alerter sur le taux de succès du cache

Pourquoi cela arrive : Les équipes définissent des seuils d'alerte trop élevés ou avec une durée for trop courte. Les modifications légitimes du Dockerfile provoquent des échecs temporaires et déclenchent des alertes bruyantes.

Comment l'éviter : Définissez des seuils réalistes basés sur des données historiques. Utilisez une période for plus longue, comme 15 minutes, pour éviter les baisses transitoires. Alertez sur les tendances, pas sur des points de données uniques.

Comment s'en remettre : Ajustez les seuils et testez avec une fenêtre de maintenance. Mettez les alertes en sourdine pendant les changements planifiés si nécessaire.

Piège 3 : Ne pas surveiller l'utilisation du disque

Pourquoi cela arrive : La taille du cache n'est pas suivie, ou les alertes ne portent que sur le taux de succès. Le disque se remplit et les builds échouent.

Comment l'éviter : Surveillez l'utilisation du disque de l'hôte avec Node Exporter ou cAdvisor. Définissez une taille de cache maximale dans BuildKit avec --max-cache-size et alertez lorsque l'utilisation dépasse un seuil sûr (par exemple, 80 % du disque).

Comment s'en remettre : Nettoyez immédiatement le cache avec docker builder prune --filter 'until=24h'. Enquêtez sur ce qui a causé la croissance, comme un changement d'images de base ou une augmentation des builds parallèles.

Piège 4 : Utiliser un cache distant sans surveiller la connectivité

Pourquoi cela arrive : Les équipes adoptent un cache distant pour la vitesse mais ne surveillent pas le succès des importations et exportations de cache. Les problèmes réseau réduisent silencieusement l'efficacité du cache.

Comment l'éviter : Surveillez buildkit_cache_imports_total et buildkit_cache_exports_total pour les échecs. Si possible, utilisez les journaux BuildKit pour détecter les erreurs de connexion. Configurez des alertes pour les baisses soudaines d'importations ou d'exportations.

Comment s'en remettre : Vérifiez la connectivité réseau et les informations d'identification. Testez avec un build simple qui utilise le cache distant. Si le cache distant est indisponible, revenez temporairement au cache local pour éviter de bloquer les builds.

Piège 5 : Ne pas valider la collecte de métriques

Pourquoi cela arrive : L'endpoint des métriques est mal configuré ou BuildKit ne fonctionne pas. Les tableaux de bord n'affichent aucune donnée et les alertes ne se déclenchent jamais.

Comment l'éviter : Configurez une alerte Prometheus pour up == 0 sur le job BuildKit. Cela garantit que vous êtes averti si l'endpoint tombe en panne. Vérifiez également manuellement les tableaux de bord régulièrement pendant la première semaine de configuration.

Comment s'en remettre : Diagnostiquez pourquoi l'endpoint est inaccessible. Vérifiez les journaux BuildKit, l'accès réseau et la configuration de collecte Prometheus. Redémarrez BuildKit si nécessaire.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour les opérations quotidiennes et les revues périodiques. Attribuez un responsable unique pour chaque élément majeur afin de garantir la responsabilité.

Vérifications quotidiennes/hebdomadaires

• [ ] Surveiller le tableau de bord du taux de succès du cache - Responsable : ingénieur DevOps en rotation. Enquêter si inférieur à 0,8 pendant plus de 30 minutes.
• [ ] Vérifier l'espace disque sur les nœuds de build - Responsable : administrateur système. S'assurer que la taille du cache est dans les limites ; déclencher un nettoyage si supérieur à 80 % d'utilisation du disque.
• [ ] Examiner les alertes - Responsable : ingénieur de garde. Acquitter et résoudre toute alerte déclenchée.
• [ ] Vérifier la collecte de métriques - Responsable : ingénieur plateforme. Vérifier Prometheus pour les lacunes dans les données ; confirmer que l'endpoint BuildKit est opérationnel.

Revue mensuelle

• [ ] Évaluer l'efficacité du cache - Responsable : responsable de l'infrastructure de build. Les taux de succès s'améliorent-ils ou se dégradent-ils ? Examiner les tendances et identifier les causes.
• [ ] Mettre à jour les seuils d'alerte - Responsable : ingénieur plateforme. Sur la base des données du mois dernier, ajuster les seuils pour réduire le bruit et détecter les vrais problèmes.
• [ ] Nettoyer l'ancien cache - Responsable : administrateur système. Exécuter docker builder prune --filter 'until=30d' pendant une fenêtre de maintenance.
• [ ] Tester les procédures de récupération - Responsable : ingénieur DevOps. Simuler une défaillance (par exemple, remplir le disque) et pratiquer le manuel de réponse aux incidents.
• [ ] Revoir les optimisations du Dockerfile - Responsable : responsable de l'équipe applicative. Chercher des opportunités d'améliorer la réutilisation du cache, comme réordonner les couches ou utiliser des builds multi-étapes.

Audit trimestriel

• [ ] Auditer la configuration du cache - Responsable : ingénieur sécurité. Examiner les endpoints du cache distant, les informations d'identification et les limites de taille. Faire pivoter les informations d'identification si nécessaire.
• [ ] Évaluer la couverture de surveillance - Responsable : ingénieur plateforme. S'assurer que tous les nœuds de build sont collectés et que les tableaux de bord reflètent tous les environnements.
• [ ] Mettre à jour les tableaux de bord - Responsable : ingénieur DevOps. Ajouter de nouvelles métriques ou visualisations en fonction des commentaires de l'équipe.
• [ ] Former les nouveaux membres de l'équipe - Responsable : chef d'équipe. Passer en revue le manuel d'incident et les tableaux de bord de surveillance avec tout nouvel ingénieur.

Chaque élément de la liste a un responsable unique et une fréquence de revue définie. Cela évite le problème courant de « tout le monde est responsable, donc personne ne l'est ».

Conclusion

La surveillance et les alertes pour le cache de build Docker sont essentielles pour maintenir des builds rapides et efficaces. Commencez par un pilote étroit : activez les métriques sur un seul nœud de build, configurez des tableaux de bord de base et créez quelques règles d'alerte. Utilisez l'inventaire des versions et les étapes de configuration sûre de ce guide pour implémenter la surveillance sans perturber les flux de travail existants. Vérifiez que les métriques sont collectées et visualisées correctement, et préparez-vous aux modes de défaillance courants avec un plan de récupération clair.

En suivant la liste de contrôle opérationnelle, vous pouvez assurer la santé continue du cache et détecter et résoudre rapidement les problèmes. Pour les prochaines étapes, envisagez d'étendre la surveillance aux caches distants, de l'intégrer aux pipelines CI/CD pour une analyse historique et d'explorer les fonctionnalités avancées de BuildKit comme les montages de cache.

Tous les exemples et nombres hypothétiques sont construits à des fins de démonstration ; ajustez les seuils et les configurations à votre environnement. Les commandes et configurations concrètes tout au long de ce guide vous donnent un point de départ que vous pouvez adapter à votre propre infrastructure.