1# events
2
3<!---MARKER_GEN_START-->
4Get real time events from the server
5
6### Aliases
7
8`docker system events`, `docker events`
9
10### Options
11
12| Name | Type | Default | Description |
13|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
14| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided |
15| [`--format`](#format) | `string` | | Format output using a custom template:<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
16| [`--since`](#since) | `string` | | Show all events created since timestamp |
17| `--until` | `string` | | Stream events until this timestamp |
18
19
20<!---MARKER_GEN_END-->
21
22## Description
23
24Use `docker events` to get real-time events from the server. These events differ
25per Docker object type. Different event types have different scopes. Local
26scoped events are only seen on the node they take place on, and Swarm scoped
27events are seen on all managers.
28
29Only the last 1000 log events are returned. You can use filters to further limit
30the number of events returned.
31
32### Object types
33
34#### Containers
35
36Docker containers report the following events:
37
38- `attach`
39- `commit`
40- `copy`
41- `create`
42- `destroy`
43- `detach`
44- `die`
45- `exec_create`
46- `exec_detach`
47- `exec_die`
48- `exec_start`
49- `export`
50- `health_status`
51- `kill`
52- `oom`
53- `pause`
54- `rename`
55- `resize`
56- `restart`
57- `start`
58- `stop`
59- `top`
60- `unpause`
61- `update`
62
63#### Images
64
65Docker images report the following events:
66
67- `delete`
68- `import`
69- `load`
70- `pull`
71- `push`
72- `save`
73- `tag`
74- `untag`
75
76#### Plugins
77
78Docker plugins report the following events:
79
80- `enable`
81- `disable`
82- `install`
83- `remove`
84
85#### Volumes
86
87Docker volumes report the following events:
88
89- `create`
90- `destroy`
91- `mount`
92- `unmount`
93
94#### Networks
95
96Docker networks report the following events:
97
98- `create`
99- `connect`
100- `destroy`
101- `disconnect`
102- `remove`
103
104#### Daemons
105
106Docker daemons report the following events:
107
108- `reload`
109
110#### Services
111
112Docker services report the following events:
113
114- `create`
115- `remove`
116- `update`
117
118#### Nodes
119
120Docker nodes report the following events:
121
122- `create`
123- `remove`
124- `update`
125
126#### Secrets
127
128Docker secrets report the following events:
129
130- `create`
131- `remove`
132- `update`
133
134#### Configs
135
136Docker configs report the following events:
137
138- `create`
139- `remove`
140- `update`
141
142### Limiting, filtering, and formatting the output
143
144#### <a name="since"></a> Limit events by time (--since, --until)
145
146The `--since` and `--until` parameters can be Unix timestamps, date formatted
147timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed
148relative to the client machine’s time. If you do not provide the `--since` option,
149the command returns only new and/or live events. Supported formats for date
150formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`,
151`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local
152timezone on the client will be used if you do not provide either a `Z` or a
153`+-00:00` timezone offset at the end of the timestamp. When providing Unix
154timestamps enter seconds[.nanoseconds], where seconds is the number of seconds
155that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap
156seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
157fraction of a second no more than nine digits long.
158
159Only the last 1000 log events are returned. You can use filters to further limit
160the number of events returned.
161
162#### <a name="filter"></a> Filtering (--filter)
163
164The filtering flag (`-f` or `--filter`) format is of "key=value". If you would
165like to use multiple filters, pass multiple flags (e.g.,
166`--filter "foo=bar" --filter "bif=baz"`)
167
168Using the same filter multiple times is interpreted as a logical `OR`; for example,
169`--filter container=588a23dac085 --filter container=a8f7720b8c22` displays
170events for container `588a23dac085` or container `a8f7720b8c22`.
171
172Using multiple filters is interpreted as a logical `AND`; for example,
173`--filter container=588a23dac085 --filter event=start` displays events for
174container `588a23dac085` and where the event type is `start`.
175
176The currently supported filters are:
177
178- config (`config=<name or id>`)
179- container (`container=<name or id>`)
180- daemon (`daemon=<name or id>`)
181- event (`event=<event action>`)
182- image (`image=<repository or tag>`)
183- label (`label=<key>` or `label=<key>=<value>`)
184- network (`network=<name or id>`)
185- node (`node=<id>`)
186- plugin (`plugin=<name or id>`)
187- scope (`scope=<local or swarm>`)
188- secret (`secret=<name or id>`)
189- service (`service=<name or id>`)
190- type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`)
191- volume (`volume=<name>`)
192
193#### <a name="format"></a> Format the output (--format)
194
195If you specify a format (`--format`), the given template is executed
196instead of the default format. Go's [text/template](https://pkg.go.dev/text/template)
197package describes all the details of the format.
198
199If a format is set to `{{json .}}`, events are streamed in the JSON Lines format.
200For information about JSON Lines, see <https://jsonlines.org/>.
201
202## Examples
203
204### Basic example
205
206You'll need two shells for this example.
207
208**Shell 1: Listening for events:**
209
210```console
211$ docker events
212```
213
214**Shell 2: Start and Stop containers:**
215
216```console
217$ docker create --name test alpine:latest top
218$ docker start test
219$ docker stop test
220```
221
222**Shell 1: (Again .. now showing events):**
223
224```console
2252017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test)
2262017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge)
2272017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2282017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2292017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2302017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2312017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
232```
233
234To exit the `docker events` command, use `CTRL+C`.
235
236### Filter events by time
237
238You can filter the output by an absolute timestamp or relative time on the host
239machine, using the following different time formats:
240
241```console
242$ docker events --since 1483283804
2432017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2442017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2452017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2462017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2472017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2482017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2492017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2502017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
251
252$ docker events --since '2017-01-05'
2532017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2542017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2552017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2562017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2572017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2582017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2592017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2602017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
261
262$ docker events --since '2013-09-03T15:49:29'
2632017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2642017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2652017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2662017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2672017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2682017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2692017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2702017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
271
272$ docker events --since '10m'
2732017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2742017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2752017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2762017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2772017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2782017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2792017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2802017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
281
282$ docker events --since '2017-01-05T00:35:30' --until '2017-01-05T00:36:05'
2832017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2842017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2852017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2862017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
287```
288
289### Filter events by criteria
290
291The following commands show several different ways to filter the `docker event`
292output.
293
294```console
295$ docker events --filter 'event=stop'
296
2972017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
2982017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain)
299
300$ docker events --filter 'image=alpine'
301
3022017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner)
3032017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
3042017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15)
3052017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9)
3062017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner)
3072017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner)
308
309$ docker events --filter 'container=test'
310
3112017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
3122017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
3132017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
3142017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
315
316$ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8'
317
3182017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
3192017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
3202017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9)
3212017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test)
3222017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test)
323
324$ docker events --filter 'container=test' --filter 'event=stop'
325
3262017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test)
327
328$ docker events --filter 'type=volume'
329
3302015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
3312015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate)
3322015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local)
3332015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)
334
335$ docker events --filter 'type=network'
336
3372015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge)
3382015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge)
339
340$ docker events --filter 'container=container_1' --filter 'container=container_2'
341
3422014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04)
3432014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04)
3442014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8)
3452014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8)
346
347$ docker events --filter 'type=volume'
348
3492015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
3502015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate)
3512015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local)
3522015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)
353
354$ docker events --filter 'type=network'
355
3562015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge)
3572015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge)
358
359$ docker events --filter 'type=plugin'
360
3612016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
3622016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
363
364$ docker events -f type=service
365
3662017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
3672017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
368
369$ docker events -f type=node
370
3712017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown)
372
373$ docker events -f type=secret
374
3752017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
3762017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
377
378$ docker events -f type=config
3792017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
3802017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
381
382$ docker events --filter 'scope=swarm'
383
3842017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson)
3852017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret)
386```
387
388### Format the output
389
390```console
391$ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}'
392
393Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
394Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
395Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
396Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
397Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
398Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
399```
400
401#### Format as JSON
402
403To list events in JSON format, use the `json` directive, which is the same
404`--format '{{ json . }}`.
405
406```console
407$ docker events --format json
408
409{"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
410{"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
411{"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e..
412{"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42..
413{"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
414```
View as plain text