Docker Engine registra un evento cada vez que el demonio realiza acciones importantes. Puede acceder al registro de eventos para identificar cuándo ocurrió una acción y realizar un seguimiento de los cambios en los objetos a lo largo del tiempo.
En este artículo, explicaremos qué se captura como eventos y cuándo es posible que desee verlos. Luego mostraremos cómo monitorear eventos en tiempo real usando Docker CLI y REST API.
Los eventos de Docker describen las actividades realizadas por su demonio Docker. La mayoría de las interacciones con objetos como contenedores, imágenes, volúmenes y redes registran un evento, creando un registro que puede utilizar para inspeccionar cambios pasados.
Hay muchos tipos diferentes de eventos que identifican cambios específicos en su entorno:
- Crear y eliminar contenedores
- Estados de verificación del estado del contenedor
- Comandos ejecutados dentro de contenedores con
docker exec
- Tirando y empujando imágenes
- Crear, destruir, montar y desmontar volúmenes
- Habilitar y deshabilitar los complementos del demonio Docker
Puedes ver la lista completa en la documentación de Docker.
Cada evento registrado incluye una marca de tiempo y la identificación del objeto afectado. Puede utilizar esta información para crear un historial de cambios en su entorno, independientemente de si observó o no sus desencadenantes originales.
Los eventos almacenados también pueden ayudar a diagnosticar problemas como fallas inesperadas en los contenedores. Ver el registro le permite identificar el momento preciso en que se detuvo un contenedor, lo que proporciona un punto de datos que puede correlacionar con sus otros registros. Los eventos pueden establecer cuándo comenzaron a fallar las comprobaciones de estado de un contenedor, reduciendo el período de interés en el que es necesario inspeccionar servicios externos para determinar la causa raíz de un problema.
Transmisión de eventos de Docker con Docker CLI
El comando CLI docker events transmite eventos desde su demonio Docker a la ventana de su terminal. Los eventos aparecerán en tiempo real hasta que finalice el proceso presionando la combinación de teclado Ctrl+C.
Para empezar, ejecutar el comando sin argumentos no mostrará ningún resultado. Solo se muestra la actividad nueva, por lo que la salida permanece vacía hasta que ocurre un evento. Puedes provocar uno iniciando un nuevo contenedor en un shell diferente:
$ docker run --rm hello-world
Ahora deberían aparecer varios eventos en la ventana de la terminal que ejecuta el comando Docker Events:
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)
...
Cada evento se muestra en su propia línea. Primero se muestra la marca de tiempo del evento, seguida del tipo de objeto afectado (como imagen o contenedor) y luego la acción que se realizó (como crear, adjuntar e iniciar). El resto del mensaje contiene metadatos útiles sobre el objeto. El ejemplo anterior revela que se extrajo la imagen hello-world:latest y se creó un contenedor a partir de ella.
Formateo de salida
La lista de eventos en bruto suele ser difícil de manejar. Puede reformatear la salida usando el indicador –format que acepta una cadena de plantilla Go:
$ docker events --format '{{ .Time }} {{ .Action }} {{ .Type}} {{ .ID }}'La ejecución de este ejemplo producirá un resultado similar a este:
1654006800 pull image hello-world:latest1654006800 create container 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378
1654006800 attach container 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378
1654006800 start container 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378
Puede obtener eventos representados como objetos JSON usando {{ json . }} como cadena de plantilla:
$ 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
}
Aquí el JSON sin formato se pasa a través de jq, por lo que está bastante impreso en su terminal. Esto hace que la información sea más fácil de escanear.
Cuando crea cadenas de formato personalizado, puede usar las propiedades en la salida JSON como referencia para los marcadores de posición admitidos. En la mayoría de los casos, deberá escribir en mayúscula la primera letra de cada propiedad, como el tiempo hasta {{ .Time }}.
Filtrado de eventos
El registro de eventos de un demonio Docker ocupado puede volverse ruidoso rápidamente. Puede limitar los eventos a una acción, objeto o tipo de objeto específico con el indicador –filter:
- eventos acoplables –filter type=container: obtiene todos los eventos relacionados con los contenedores.
- docker events –filter event=create: obtiene eventos de creación de contenedores.
- docker events –filter container=demo-container: obtiene todos los eventos guardados para el contenedor llamado demo-container (puede hacer referencia al ID o nombre del contenedor).
Además del contenedor, puedes filtrar por todos los compatibles. nombres de tipos de objetos como imagen, red y volumen.
Se admiten múltiples filtros cuando se repite el indicador –filter. Los distintos filtros se interpretan como condiciones Y lógicas; múltiples usos del mismo filtro se convierten en cláusulas OR. A continuación se muestra un ejemplo que muestra el evento de creación tanto para el contenedor de aplicaciones como para el contenedor de API:
$ docker events \--filter container=app-container
--filter container=api-container
--filter event=create
Accediendo a eventos históricos
docker events por defecto muestra solo los eventos almacenados desde que se ejecutó el comando. Puede incluir eventos históricos agregando la bandera –since. Esto acepta una expresión de tiempo legible por humanos o una marca de tiempo absoluta:
$ docker events --since 1h$ docker events --since '2021-05-01T16:00:00'
Los eventos grabados después del tiempo indicado se mostrarán inmediatamente en su terminal. Los nuevos eventos seguirán apareciendo en tiempo real a medida que se graben.
Puede excluir eventos después de un tiempo determinado con el indicador –hasta. Funciona de manera similar a –since. El uso de –hasta deshabilitará la transmisión en tiempo real de nuevos eventos porque quedarían fuera del período de tiempo solicitado.
Transmisión de eventos de Docker desde la API REST de Daemon
Otra forma de acceder a los eventos almacenados es a través de la API REST del demonio Docker. Puede utilizar el punto final /events para transmitir eventos en tiempo real después de haber habilitó la API en su host Docker. Los eventos se devolverán en formato 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
}
El punto final de API admite parámetros de filtro, desde y hasta que tienen el mismo comportamiento que sus homólogos de CLI. A continuación se explica cómo recuperar todos los eventos de creación de contenedores registrados en la última hora:
$ curl http://127.0.0.1:2375/v1.41/events?since=1h&filters={'type':'container','action':'create'}Envío de eventos a un servicio externo
Docker carece de una forma integrada de enviar eventos a un servicio externo. Esto podría resultar útil si desea que todas sus creaciones de contenedores se registren en una plataforma de monitoreo o auditoría existente.
Puede configurar su propia solución creando un servicio del sistema que ejecute continuamente eventos de Docker. Debería enviar cada nueva línea de salida a su sistema externo.
Primero escriba un script Bash que implemente la funcionalidad que necesita:
#!/bin/bashdocker 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
Ahora cree una nueva unidad de servicio systemd en /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
Finalmente recarga systemd para cargar tu servicio, luego inicia y habilita la unidad:
$ sudo systemctl daemon-reload$ sudo systemctl start docker-events
$ sudo systemctl enable docker-events
Su servicio ahora transmitirá cada nuevo evento a su plataforma de monitoreo. Habilitar el servicio lo configura para que se inicie automáticamente cada vez que se reinicie su host.
Resumen
Los eventos de Docker se crean cada vez que el demonio modifica objetos en su entorno. La transmisión del registro de eventos le permite monitorear la actividad del demonio en tiempo real. Esto puede ayudarle a depurar problemas, auditar cambios y garantizar el cumplimiento.
Como los eventos se recuperan directamente del servidor Docker, no se debe confiar en ellos si necesita recuperar información en el futuro. Sólo se conservan 1.000 entradas de forma continua y no puede acceder a los eventos a través del sistema de archivos de su host Docker. El mecanismo es más adecuado para tareas rápidas ad hoc en las que se busca información específica relacionada con una actividad reciente. Para una retención a largo plazo, debe utilizar su propio servicio del sistema para enviar eventos a un repositorio externo.
