Comment afficher l'historique des événements de votre installation Docker

Publié: 2022-08-11

Logo Docker

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.

Que sont les événements Docker ?

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
  • 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 commande CLI docker events 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, de sorte que la sortie reste 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 bonjour-monde

Plusieurs événements devraient maintenant apparaître dans la fenêtre du terminal qui exécute la commande docker events :

 2022-05-31T15: 20: 00.267970018 + 01: 00 extrait d'image bonjour-monde: dernier (nom = bonjour-monde)
2022-05-31T15:20:00.347054862+01:00 création de conteneur 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378 (image=hello-world, name=nifty_morse)
2022-05-31T15:20:00.347805277+01:00 attachement de conteneur 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378 (image=hello-world, name=nifty_morse)
2022-05-31T15:20:00.621070053+01:00 démarrage du conteneur 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é (comme image ou container ), puis de l'action qui a été entreprise (comme create , attach et start ). Le reste du message contient des métadonnées utiles sur l'objet. L'exemple ci-dessus révèle que l'image hello-world:latest a été extraite et qu'un conteneur a été créé à partir de celle-ci.

Formatage de la sortie

La liste brute des événements est souvent peu maniable. Vous pouvez reformater la sortie à l'aide de l'indicateur --format 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:dernier
1654006800 créer un conteneur 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378
1654006800 fixer le conteneur 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378
1654006800 conteneur de démarrage 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378

Vous pouvez obtenir des événements représentés sous forme d'objets JSON en utilisant {{ json . }} {{ json . }} comme chaîne de modèle :

 $ docker events --format '{{ json . }}' | jq
{
  "statut": "créer",
  "id": "4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378",
  "de": "bonjour-monde",
  "Type": "conteneur",
  "Action": "créer",
  "Acteur de cinéma": {
    "ID": "4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378",
    "Les attributs": {
      "image": "bonjour-monde",
      "nom": "nifty_morse"
    }
  },
  "portée": "locale",
  "heure": 1654006800,
  "timeNano": 1654006800347054800
}

Ici, le JSON brut est passé par 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é, comme time to {{ .Time }} .

Filtrage des événements

Le journal des événements d'un démon Docker occupé peut rapidement devenir bruyant. Vous pouvez limiter les événements à une action, un objet ou un type d'objet spécifique avec l'indicateur --filter :

  • docker events --filter type=container – Récupère tous les événements liés aux conteneurs.
  • docker events --filter event=create – Récupère les événements de création de conteneur.
  • docker events --filter container=demo-container – Récupère 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 container , vous pouvez filtrer par tous les noms de type d'objet pris en charge tels que image , network et volume .

Plusieurs filtres sont pris en charge lorsque vous répétez l'indicateur --filter . Les filtres distincts sont interprétés comme des conditions ET logiques ; plusieurs utilisations du même filtre deviennent des clauses OR . Voici un exemple qui expose l'événement create pour les app-container et api-container container :

 $ événements docker \
    --filter container=app-container
    --filter container=api-container
    --filter event=créer

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 l'indicateur --since . Cela accepte une expression temporelle lisible par l'homme ou un horodatage absolu :

 $ événements docker --depuis 1h
$ événements docker --depuis le '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 l'indicateur --until . Cela fonctionne de la même manière que --since . L'utilisation --until désactivera la diffusion en temps réel des nouveaux événements, car ils tomberaient 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 point de terminaison /events 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": "conteneur",
  "Action": "créer",
  "Acteur de cinéma": {
    "ID": "4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378",
    "Les attributs": {
      "image": "bonjour-monde",
      "nom": "nifty_morse"
    }
  },
  "portée": "locale",
  "heure": 1654006800,
  "timeNano": 1654006800347054800
}

Le point de terminaison de l'API prend en charge les paramètres filter , since et until qui ont le même comportement 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 exécute en permanence des 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
événements docker --format '{{ .Time }} {{ .Action }} {{ .Type }} {{ .ID }}' | lors de la lecture de l'événement
fais
    boucle \
        -X POSTE \
        -H "Type de contenu : application/json" \
        -d '{"événement": "$événement"}' \
        https://example.com/events
Fini

Créez maintenant une nouvelle unité de service systemd dans /etc/systemd/system/docker-events.service :

 [Unité]
Description=Service de surveillance des événements Docker personnalisé

[Service]
Type = bifurcation
ExecStart=/usr/local/bin/docker-events.sh

[Installer]
WantedBy=multi-utilisateur.cible

Enfin, rechargez 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.