События Docker: руководство по мониторингу

Логотип Docker

Быстрые ссылки

Streaming Docker Events With the Docker CLI
Streaming Docker Events From the Daemon REST API
Sending Events to an External Service
Summary

Docker Engine фиксирует событие каждый раз, когда демон выполняет значимое действие. Журнал событий помогает понять, когда произошло действие, и составить хронологию изменений объектов: контейнеров, образов, томов и сетей. В этом материале описано, какие события фиксируются, как их просматривать в реальном времени и как перенаправлять их в внешние системы.

Краткое определение: событие Docker — это JSON-объект или текстовая запись, отражающая действие демона над объектом (контейнер, образ, том, сеть), включая временную метку и идентификатор объекта.

Important: события ориентированы на оперативный мониторинг и отладку; их не стоит воспринимать как полноценный долговременный аудит без перенаправления в внешнее хранилище.

Что фиксируется как событие

Docker регистрирует множество типов действий. Типичные события включают:

создание и удаление контейнеров;
статусы проверки здоровья контейнера (health check);
команды, выполненные внутри контейнеров с помощью docker exec;
операции pull и push образов;
создание, удаление, монтирование и отмонтирование томов;
включение и отключение плагинов демона Docker.

Каждое событие содержит временную метку и ID затронутого объекта. Эти данные позволяют восстановить историю изменений, даже если вы изначально не наблюдали триггер события.

Когда смотреть события:

отладка неожиданной остановки контейнера — событие укажет точное время остановки;
проверка стабильности службы — события healthcheck помогут сузить интервал поиска проблемы;
аудит изменений окружения — кто создал/удалил контейнеры и когда.

Просмотр событий в реальном времени с помощью Docker CLI

Команда docker events транслирует поток событий демона в ваш терминал. Поток продолжается до прерывания (Ctrl+C).

Запуск без аргументов выводит только новые события: сначала терминал пуст, пока не произойдёт действие. Например, в другом терминале выполните:

$ docker run --rm hello-world

В терминале с запущенной командой 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)

Каждое событие выводится в отдельной строке: сначала метка времени, затем тип объекта (image, container и т. п.), действие (create, attach, start) и метаданные (имя или image).

Форматирование вывода

Сырые строки часто неудобны. Флаг --format принимает Go-шаблон. Пример:

$ docker events --format '{{ .Time }} {{ .Action }} {{ .Type}} {{ .ID }}'

Вывод может выглядеть так:

1654006800 pull image hello-world:latest

1654006800 create container 4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378

Для получения JSON-объектов используйте {{ json . }} и, при необходимости, форматируйте с помощью jq:

$ 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
}

Обратите внимание: при создании собственных шаблонов используйте имена полей с заглавной буквы (например, {{ .Time }}), как в JSON-выводе.

Фильтрация событий

Для загруженного демона журнал быстро становится шумным. Уменьшите поток с помощью --filter:

docker events --filter type=container — только события, связанные с контейнерами.
docker events --filter event=create — события создания.
docker events --filter container=demo-container — все события для контейнера demo-container (можно использовать ID или имя).

Допустимые типы: container, image, network, volume и другие, поддерживаемые Docker.

Несколько фильтров интерпретируются как логическое AND; повторение одного и того же фильтра превращается в OR. Пример — показать события создания для двух контейнеров:

$ docker events \
  --filter container=app-container \
  --filter container=api-container \
  --filter event=create

Доступ к историческим событиям

По умолчанию docker events показывает только те события, которые записываются после запуска команды. Для просмотра исторических записей используйте --since с человеческим выражением или абсолютной временной меткой:

$ docker events --since 1h

$ docker events --since '2021-05-01T16:00:00'

События после указанного времени будут сразу показаны; поток по-прежнему продолжается в реальном времени.

Флаг --until исключает события после указанной метки и отключает реальное время, так как новые события будут за пределами периода:

$ docker events --since '2021-05-01T12:00:00' --until '2021-05-01T13:00:00'

Стриминг событий через REST API демона

Помимо CLI, события доступны через REST API демона Docker на эндпоинте /events. Включив API на хосте, вы получите JSON-поток:

$ curl http://127.0.0.1:2375/v1.41/events

Пример записи (JSON):

{
  "Type": "container",
  "Action": "create",
  "Actor": {
    "ID": "4a6c8d34a183363db5dbfdcc3cab4c82c4a341d719df56ec2e7f879ee8f02378",
    "Attributes": {
      "image": "hello-world",
      "name": "nifty_morse"
    }
  },
  "scope": "local",
  "time": 1654006800,
  "timeNano": 1654006800347054800
}

Параметры filters, since и until работают аналогично CLI. Пример: получить все события создания контейнеров за последний час:

$ curl "http://127.0.0.1:2375/v1.41/events?since=1h&filters={'type':'container','action':'create'}"

Security note: публичный HTTP API по порту 2375 не защищён шифрованием и не рекомендуем к использованию в открытых сетях. При необходимости используйте UNIX-сокет, TLS или проксирование через защищённый канал.

Отправка событий во внешнюю систему

Docker не предоставляет встроенной возможности автоматически отсылать события в сторонние системы. Для долгосрочного хранения и аудита создайте сервис, который постоянно читает docker events и пересылает каждую запись в ваш репозиторий логов, SIEM или очередь сообщений.

Ниже — минимальный пример Bash-скрипта и unit-файла systemd.

Пример Bash-скрипта /usr/local/bin/docker-events.sh:

#!/bin/bash

docker events --format '{{ json . }}' | while read event
 do
  curl -X POST -H "Content-Type: application/json" -d "${event}" https://example.com/events
 done

Важно: в примере мы отправляем уже сериализованный JSON (используется {{ json . }}). Перед отправкой на внешнюю систему подумайте о фильтрации, агрегации и анонимизации полей (имён контейнеров, токенов), если это требуется политиками безопасности или законами о защите данных.

Пример systemd unit /etc/systemd/system/docker-events.service:

[Unit]
Description=Custom Docker Event Monitoring Service

[Service]
Type=simple
ExecStart=/usr/local/bin/docker-events.sh
Restart=always

[Install]
WantedBy=multi-user.target

После создания перезагрузите конфигурацию systemd и включите сервис:

$ sudo systemctl daemon-reload
$ sudo systemctl start docker-events
$ sudo systemctl enable docker-events

Совет: поместите скрипт под пользователя с ограниченными правами и дайте ему доступ только к тому, что необходимо. Рассмотрите отправку событий через очередь (Kafka, RabbitMQ) для буферизации во время перебоев сети.

Практическое руководство: методология отправки событий во внешнюю систему

Выберите транспорт: HTTPS (REST), syslog, AMQP, Kafka или облачный ingestion (CloudWatch, Stackdriver, Logz).
Решите формат хранения: сырые JSON-события или проиндексированные записи (time, type, action, id, attributes).
Реализуйте фильтрацию на агрегацию на агенте (чтобы снизить шум).
Добавьте бэфферизацию (локальный файл или очередь) на случай временной недоступности приемника.
Реализуйте ретрай и дедупликацию при необходимости.
Обеспечьте шифрование канала и контроль доступа (TLS, API-ключи, IAM).
Подумайте о ретенции и правилах удаления (GDPR/локальные требования).

Мини-методология в виде шагов для быстрого запуска:

тестовый стенд: включите локальный приемник и отправляйте события из скрипта;
отладка: добавьте логирование ошибок при доставке, сохранение неотправленных сообщений;
прод: задеплойте systemd unit, мониторьте lag и ошибки доставки.

Шаблон: чек-листы по ролям

DevOps / SRE:

настроить сбор событий на всех хостах;
обеспечить централизованную доставку в систему мониторинга;
настроить ретеншн и ротацию лога;
протестировать восстановление после недоступности приемника.

Разработчик:

проверять события при локальном тестировании (docker events);
формировать ясные имена контейнеров/лэйблы для упрощённой фильтрации;
избегать в контейнерных именах секретов.

Security / Compliance:

оценить, какие данные попадают в events (имена, метаданные);
реализовать анонимизацию/маскирование при отправке в внешние сервисы;
контролировать доступ к API и конечным точкам приёма.

Шпаргалка (Cheat sheet) — полезные команды

Запустить поток событий в реальном времени:

docker events

Форматированный вывод (время, действие, тип, ID):

docker events --format '{{ .Time }} {{ .Action }} {{ .Type}} {{ .ID }}'

JSON-вывод и форматирование через jq:

docker events --format '{{ json . }}' | jq

Фильтрация по типу и событию:

docker events --filter type=container --filter event=die

Исторические события за последний час:

docker events --since 1h

Через REST API (простой пример):

curl "http://127.0.0.1:2375/v1.41/events?since=1h&filters={'type':'container','action':'create'}"

Когда механизм событий не подойдёт (ограничения и кейсы отказа)

Долговременный аудит: Docker хранит ограниченное число записей (по умолчанию — 1 000 записей на rolling basis), поэтому журнал не является заменой полноценного решения для аудита.
Параллельные инстансы: если у вас несколько демонов, события собираются локально на каждом хосте — требуется централизованный сбор.
Безопасность: если API демона открыт без TLS, это риск; также события могут содержать чувствительные имена и метаданные.
Высокая нагрузка: при экстремальном количестве событий удобнее собирать агрегированную и отфильтрованную информацию, а не весь поток.

Сравнение альтернатив

docker events (локально) — быстро, в реальном времени, ограниченная ретенция.
REST API демона — удобно для интеграции, те же ограничения безопасности.
Использование логов контейнеров и драйверов логирования — больше данных об приложении, но не все изменения инфраструктуры.
SIEM/агенты (Filebeat, Fluentd) — хороши для централизации и ретенции.

Безопасность и приватность

Не открывайте порт 2375 в публичный доступ. Если нужно управлять демоном удалённо, используйте TLS (2376) или туннелирование через SSH/VPN.
Перед отправкой событий во внешние сервисы подумайте о маскировании полей, содержащих имена контейнеров или пути, если это регулируется политиками конфиденциальности.
Контролируйте права доступа к сервису, который читает docker events, чтобы не допустить утечки информации.

Note: события не содержат содержимого файлов в контейнере и не раскрывают внутренние данные приложений, но метаданные могут быть чувствительными.

Диагностика и типичные сценарии устранения неполадок

Проблема: отсутствуют события при выполнении действий

Проверьте, запущен ли демон Docker на хосте.
Убедитесь, что вы подключены к правильному Docker host (локальный сокет vs удалённый API).
Если используете --since, убедитесь, что время указано корректно.

Проблема: события приходят, но внешний приёмник не получает их

Проверьте сетевую доступность конечной точки (curl/telemetry logs).
Посмотрите журналы вашего systemd-сервиса: journalctl -u docker-events.
Добавьте логи ошибок в скрипт отправки и параметры ретрая.

Факт-бокс: ключевые числа и свойства

Ретенция событий: 1 000 записей (rolling) — встроенное ограничение Docker (как указано в документации).
Формат времени: события содержат both time (unix seconds) и timeNano (наносекунды).
Формат данных: docker events может выводить как текст, так и JSON ({{ json . }}).

Краткое резюме

Docker events — полезный инструмент для оперативного мониторинга и отладки активности демона: создания контейнеров, pull/push образов, статусных проверок и прочего. Для просмотра используйте docker events с форматированием и фильтрами или REST API демона. Для долговременного хранения и соответствия требованиям аудита создайте агент, который будет перенаправлять события в централизованную систему хранения, с учётом шифрования, анонимизации и буферизации.

Ключевые рекомендации:

Используйте docker events для оперативной диагностики и локального мониторинга.
Для долгосрочного аудита реализуйте сбор и отправку событий в централизованную систему.
Обеспечьте защиту канала и маскирование чувствительных метаданных.

Ссылки для дальнейшего чтения (оригинальная документация Docker): https://docs.docker.com/engine/.

Сводка

События помогают восстановить историю изменений демона Docker и упрощают отладку.
Команда docker events и эндпоинт /events демона — основные способы доступа к ним.
Для производственных систем настройте централизованный сбор, шифрование и политику ретенции.