Watch Docker Events Without Losing the Useful Detail

You will finish with a practical event watcher for Docker: a live stream for an incident, a bounded query for recent activity, filters for one container or event type, and JSON Lines output for a script. The examples use Docker CLI 29.8.1 from docker-ce-cli package version 5:29.8.1-1~ubuntu.24.04~noble on this machine.

Allow about fifteen minutes. You need the Docker CLI and access to a Docker daemon. Most commands are ordinary user commands, but your account must be allowed to contact the daemon. This guide only reads the event stream, apart from the deliberately optional test container workflow. It does not remove containers, images, volumes or networks.

1. Check the installed command

Start by checking the command and its available options:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker system events --help
Usage:  docker system events [OPTIONS]

Get real time events from the server

docker system events and docker events are aliases. Use the longer form in scripts when clarity matters. The command needs a reachable daemon even when you only want to read events. If it reports a socket or permission error, check docker context show and your Docker access before adding sudo. Running the CLI as root can select a different configuration and context.

2. Watch new events as they happen

Run the command without a start time:

$ docker system events
2026-09-23T10:14:02.123456789+01:00 container start 0123456789ab (image=example:1, name=example)

Without --since, the command waits for new and live events. It does not begin by printing an unlimited history. Each line identifies a time, object type, action and object ID, followed by available attributes. The exact timestamp, ID and attributes depend on the event.

Leave this command running in one shell while you investigate in another. Press Ctrl+C to stop the watcher. Stopping the watcher does not stop or change any Docker object.

To create a known, temporary event sequence, use a test image and an explicitly named container only if pulling and running that image is acceptable in your environment:

$ docker create --name events-test alpine:latest true
$ docker start events-test
$ docker stop events-test
$ docker rm events-test

These commands do change Docker state and the final command removes the test container. Skip them on a production daemon or where image pulls are not approved. If you stop after docker create or docker start, recover with docker rm -f events-test when you are certain that name belongs to this test.

3. Replay a recent, bounded window

Use --since with a Go duration to inspect recent history. This example asks for the last three minutes:

$ docker system events --since 3m --until 0s
2026-09-23T10:12:41.500000000+01:00 container die 0123456789ab (image=example:1, name=example)
2026-09-23T10:12:41.600000000+01:00 container stop 0123456789ab (image=example:1, name=example)

--since and --until accept Unix timestamps, supported date formats such as 2026-09-23 and RFC3339 timestamps, as well as durations such as 10m and 1h30m. Durations are relative to the client machine's clock. The local timezone is used for a date without a timezone offset, so use an explicit offset when a query must be unambiguous.

The --until value is a useful guard against leaving a command attached to a terminal. For a fixed absolute interval, use timestamps with an offset:

$ docker system events \
    --since '2026-09-23T09:00:00+01:00' \
    --until '2026-09-23T09:05:00+01:00'

If a bounded query prints nothing, that can simply mean no matching events were retained in the interval. It is not proof that the daemon was idle outside that interval.

4. Narrow the stream with filters

Filters use key=value. This command shows only container stop events:

$ docker system events \
    --since 30m \
    --filter 'type=container' \
    --filter 'event=stop'
2026-09-23T10:13:02.000000000+01:00 container stop 0123456789ab (image=example:1, name=example)

Different filter keys are combined as a logical AND. Repeating the same key is an OR, so this watches two known container names:

$ docker system events \
    --filter 'container=web' \
    --filter 'container=worker'

Useful filters include container, event, image, label, network, service, type and volume. The official CLI also supports object types such as daemon, node, secret and config where the daemon exposes those events. Quote the complete filter, especially when the value contains spaces or shell characters.

Do not confuse an event filter with an action. --filter 'event=stop' observes stop events; it does not stop anything. If a filter returns nothing, first remove the filters and use a short --since window to establish that the daemon is producing events.

5. Choose text or JSON output

The default text is convenient at a terminal. For a stable, machine-readable stream, use the JSON template:

$ docker system events \
    --since 10m \
    --filter 'type=container' \
    --format '{{json .}}'
{"status":"start","id":"0123456789abcdef","from":"example:1","Type":"container","Action":"start"}

Each event is emitted as one JSON object per line, known as JSON Lines. Fields vary by object and event, so consumers should tolerate fields they do not need and should not assume that every event has the same attributes. The full ID and attribute set can be longer than the illustrative line above.

You can select fields for a compact human-readable report with a Go template:

$ docker system events \
    --since 10m \
    --filter 'type=container' \
    --format 'type={{.Type}} status={{.Status}} id={{.ID}}'
type=container status=start id=0123456789abcdef

Use {{json .}} when another program must parse the result. Keep a terminal-friendly template for a human incident log. Template fields are event data, not shell variables, so do not add shell expansion around them.

6. Diagnose gaps without guessing

Docker event history is limited. The current Docker reference documents that only the last 256 log events are returned, and filters can reduce what you see further. An old event that is absent from a query may have fallen outside the retained window rather than never having happened.

Check the client context when the output contradicts what you saw elsewhere:

$ docker context show
default
$ docker info --format '{{.ServerVersion}}'
29.8.1

The event time is based on the Docker daemon's events, while relative time arguments are computed from the client machine's clock. A clock mismatch can make a duration query surprising. For incident records, prefer an absolute timestamp with an explicit timezone and record the context and daemon version alongside the output.

Do not add elevated privileges as a first troubleshooting step. If an unprivileged command can read docker info, it should normally be able to read events in the same context. If access is denied, ask the system administrator to review the daemon socket and group policy rather than copying sensitive event output into a privileged shell.