Docker Engine enregistre un événement chaque fois que des actions importantes sont entreprises par le démon. Vous pouvez accéder au journal des événements pour identifier le moment où une action s’est produite et suivre les modifications apportées aux objets au fil du temps.
Dans cet article, nous expliquerons ce qui est capturé en tant qu’événements et quand vous voudrez peut-être les afficher. Nous montrerons ensuite comment surveiller les événements en temps réel à l’aide de la CLI Docker et de l’API REST.
Les événements Docker décrivent les activités entreprises par votre démon Docker. La plupart des interactions avec des objets tels que des conteneurs, des images, des volumes et des réseaux enregistrent un événement, créant un journal que vous pouvez utiliser pour inspecter les modifications passées.
Il existe de nombreux types d’événements différents qui identifient des changements spécifiques dans votre environnement :
- Création et suppression de conteneurs
- États de la vérification de l’état des conteneurs
- Les commandes exécutées à l’intérieur des conteneurs avec
docker exec - Tirer et pousser des images
- Créer, détruire, monter et démonter des volumes
- Activation et désactivation des plugins du démon Docker
Vous pouvez consulter la liste complète dans la documentation de Docker.
Chaque événement enregistré comprend un horodatage et l’ID de l’objet affecté. Vous pouvez utiliser ces informations pour assembler un historique des modifications apportées à votre environnement, que vous ayez observé ou non leurs déclencheurs d’origine.
Les événements stockés peuvent également aider à diagnostiquer des problèmes tels que des échecs de conteneur inattendus. L’affichage du journal vous permet d’identifier l’heure précise à laquelle un conteneur s’est arrêté, fournissant un point de données que vous pouvez corréler avec vos autres journaux. Les événements peuvent établir le moment où les vérifications de l’état d’un conteneur ont commencé à échouer, réduisant ainsi la période d’intérêt au cours de laquelle vous devez inspecter des services externes pour déterminer la cause première d’un problème.
Diffusion d’événements Docker avec l’interface de ligne de commande Docker
La docker events La commande CLI diffuse les événements de votre démon Docker dans la fenêtre de votre terminal. Les événements apparaîtront en temps réel jusqu’à ce que vous terminiez le processus en appuyant sur la combinaison de touches Ctrl+C.
L’exécution de la commande sans arguments n’affichera aucune sortie pour commencer. Seule une nouvelle activité est affichée, la sortie reste donc vide jusqu’à ce qu’un événement se produise. Vous pouvez en provoquer un en démarrant un nouveau conteneur dans un shell différent :
$ docker run --rm hello-world
Plusieurs événements devraient maintenant apparaître dans la fenêtre du terminal qui exécute le docker events commande:
2022-05-31T15:20:00.267970018+01:00 image pull hello-world:latest (name=hello-world) 2022-05-31T15:20:00.347054862+01:00 container create 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378 (image=hello-world, name=nifty_morse) 2022-05-31T15:20:00.347805277+01:00 container attach 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378 (image=hello-world, name=nifty_morse) 2022-05-31T15:20:00.621070053+01:00 container start 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378 (image=hello-world, name=nifty_morse) ...
Chaque événement s’affiche sur sa propre ligne. L’horodatage de l’événement s’affiche en premier, suivi du type d’objet affecté (tel que image ou container) puis l’action qui a été entreprise (comme create, attachet start). Le reste du message contient des métadonnées utiles sur l’objet. L’exemple ci-dessus révèle que le hello-world:latest l’image a été extraite et un conteneur créé à partir de celle-ci.
Formatage de la sortie
La liste brute des événements est souvent peu maniable. Vous pouvez reformater la sortie en utilisant le --format drapeau qui accepte une chaîne de modèle Go :
$ docker events --format ' .Time .Action .Type .ID '
L’exécution de cet exemple produira une sortie qui ressemble à ceci :
1654006800 pull image hello-world:latest 1654006800 create container 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378 1654006800 attach container 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378 1654006800 start container 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378
Vous pouvez obtenir des événements représentés sous forme d’objets JSON en utilisant json . comme chaîne de modèle :
$ docker events --format ' json . ' | jq
"status": "create",
"id": "4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378",
"from": "hello-world",
"Type": "container",
"Action": "create",
"Actor":
"ID": "4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378",
"Attributes":
"image": "hello-world",
"name": "nifty_morse"
,
"scope": "local",
"time": 1654006800,
"timeNano": 1654006800347054800
Ici, le JSON brut est transmis jq il est donc assez imprimé dans votre terminal. Cela rend les informations plus faciles à parcourir.
Lorsque vous créez des chaînes de format personnalisées, vous pouvez utiliser les propriétés de la sortie JSON comme référence pour les espaces réservés pris en charge. Dans la plupart des cas, vous devrez mettre en majuscule la première lettre de chaque propriété, par exemple time à .Time .
Filtrage des événements
Le journal des événements d’un démon Docker occupé peut rapidement devenir bruyant. Vous pouvez restreindre les événements à une action, un objet ou un type d’objet spécifique avec la --filter drapeau:
docker events --filter type=container– Obtenir tous les événements liés aux conteneurs.docker events --filter event=create– Obtenir des événements de création de conteneur.docker events --filter container=demo-container– Obtenez tous les événements enregistrés pour le conteneur appelédemo-container(vous pouvez référencer l’ID ou le nom du conteneur).
Outre containervous pouvez filtrer par tous les noms de type d’objet pris en charge tels que image, networket volume.
Plusieurs filtres sont pris en charge lorsque vous répétez --filter drapeau. Les filtres distincts sont interprétés comme logiques ET les conditions; plusieurs utilisations du même filtre deviennent OU clauses. Voici un exemple qui met en évidence le create événement pour les deux app-container et api-container conteneurs :
$ docker events
--filter container=app-container
--filter container=api-container
--filter event=create
Accéder aux événements historiques
docker events affiche par défaut uniquement les événements stockés depuis l’exécution de la commande. Vous pouvez inclure des événements historiques en ajoutant le --since drapeau. Cela accepte une expression temporelle lisible par l’homme ou un horodatage absolu :
$ docker events --since 1h $ docker events --since '2021-05-01T16:00:00'
Les événements enregistrés après l’heure indiquée seront immédiatement affichés dans votre terminal. De nouveaux événements continueront d’apparaître en temps réel au fur et à mesure de leur enregistrement.
Vous pouvez exclure des événements après un certain temps avec le --until drapeau. Cela fonctionne de la même manière que --since. Utilisant --until désactivera la diffusion en temps réel des nouveaux événements, car ils se situeraient en dehors de la période demandée.
Diffusion d’événements Docker à partir de l’API Daemon REST
Une autre façon d’accéder aux événements stockés consiste à utiliser l’API REST du démon Docker. Vous pouvez utiliser le /events point de terminaison pour diffuser des événements en temps réel après avoir activé l’API sur votre hôte Docker. Les événements seront renvoyés au format JSON :
$ curl http://127.0.0.1:2375/v1.41/events
"Type": "container",
"Action": "create",
"Actor":
"ID": "4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378",
"Attributes":
"image": "hello-world",
"name": "nifty_morse"
,
"scope": "local",
"time": 1654006800,
"timeNano": 1654006800347054800
Le point de terminaison de l’API prend en charge filter, sinceet until paramètres qui ont les mêmes comportements que leurs homologues CLI. Voici comment récupérer tous les événements de création de conteneurs enregistrés au cours de l’heure écoulée :
$ curl http://127.0.0.1:2375/v1.41/events?since=1h&filters='type':'container','action':'create'
Envoi d’événements à un service externe
Docker ne dispose pas d’un moyen intégré d’envoyer des événements à un service externe. Cela peut être utile si vous souhaitez que toutes vos créations de conteneurs soient enregistrées dans une plateforme de surveillance ou d’audit existante.
Vous pouvez configurer votre propre solution en créant un service système qui s’exécute en permanence docker events. Il doit envoyer chaque nouvelle ligne de sortie à votre système externe.
Écrivez d’abord un script Bash qui implémente la fonctionnalité dont vous avez besoin :
#!/bin/bash
docker events --format ' .Time .Action .Type .ID ' | while read event
do
curl
-X POST
-H "Content-Type: application/json"
-d '"event": "$event"'
https://example.com/events
done
Créez maintenant un nouveau systemd unité de service à /etc/systemd/system/docker-events.service:
[Unit] Description=Custom Docker Event Monitoring Service [Service] Type=forking ExecStart=/usr/local/bin/docker-events.sh [Install] WantedBy=multi-user.target
Enfin recharger systemd pour charger votre service, puis démarrez et activez l’unité :
$ sudo systemctl daemon-reload $ sudo systemctl start docker-events $ sudo systemctl enable docker-events
Votre service diffusera désormais chaque nouvel événement sur votre plateforme de surveillance. L’activation du service le configure pour qu’il démarre automatiquement à chaque redémarrage de votre hôte.
Sommaire
Des événements Docker sont créés chaque fois que le démon modifie des objets dans votre environnement. La diffusion en continu du journal des événements vous permet de surveiller l’activité du démon en temps réel. Cela peut vous aider à déboguer les problèmes, à auditer les modifications et à garantir la conformité.
Comme les événements sont récupérés directement à partir du serveur Docker, il ne faut pas s’y fier si vous devez récupérer des informations à l’avenir. Seules 1 000 entrées sont conservées en continu et vous ne pouvez pas accéder aux événements via le système de fichiers de votre hôte Docker. Le mécanisme est le mieux adapté aux tâches ponctuelles rapides où vous recherchez des informations spécifiques liées à une activité récente. Pour une conservation à long terme, vous devez utiliser votre propre service système pour envoyer des événements à un référentiel externe.