Events

Purpose

The daemon publishes events for nearly every operation: container create/start/die, image pull/tag/delete, network create, volume mount, swarm changes, and so on. Events are streamed over the API at /events and consumed by clients like docker events.

The pub/sub bus is daemon/events/ (with events_filter.go for client-side filter expressions). The transport package built on top is github.com/moby/pubsub (vendored).

Architecture

graph LR
  Daemon -->|Log(event)| Bus[events.Events]
  Bus --> Topic[per-topic queue]
  Topic --> Sub1[Subscriber 1]
  Topic --> Sub2[Subscriber 2]
  Sub1 --> APIClient[/events client/]
  Sub2 --> Internal[internal listener]

Daemon.EventsService is one global instance. Code that emits an event calls EventsService.Log(action, eventType, attributes) (see usages throughout daemon/). The service stores recent events in a small in-memory ring so late subscribers can backfill, then fans out to live subscribers.

API

The system router (daemon/server/router/system/) registers GET /events. The handler subscribes, applies the client's filter expression, and streams JSON events as a chunked response. Time-range parameters (since, until) replay from the in-memory buffer.

Filters

Event filters use the shared filter syntax from api/types/filters/ — a JSON object mapping field name to a list of allowed values. Examples:

docker events --filter type=container --filter event=die
docker events --filter container=my-app --filter image=nginx

Internal subscribers

Some daemon subsystems also subscribe internally. The Swarm cluster executor uses container events to track task state. The Builder uses image events to invalidate cached intermediates.

Entry points for modification

• New event type: emit via Daemon.LogContainerEvent / Daemon.LogImageEvent / etc., document in api/swagger.yaml if it adds a new Type.
• Adjust retention: see the buffer settings in daemon/events/events.go.