From 71e220fc1173b96c468f249e6d7d728a2a7cbebe Mon Sep 17 00:00:00 2001 From: Akihiro Suda Date: Fri, 2 Sep 2016 07:40:06 +0000 Subject: [PATCH] add `docker events --format` Signed-off-by: Akihiro Suda --- contrib/completion/bash/docker | 2 +- contrib/completion/fish/docker.fish | 1 + contrib/completion/zsh/_docker | 3 ++- docs/reference/commandline/events.md | 30 ++++++++++++++++++++++++++++ man/docker-events.1.md | 29 +++++++++++++++++++++++++++ 5 files changed, 63 insertions(+), 2 deletions(-) diff --git a/contrib/completion/bash/docker b/contrib/completion/bash/docker index 8daaee30f5..39b7863300 100644 --- a/contrib/completion/bash/docker +++ b/contrib/completion/bash/docker @@ -1162,7 +1162,7 @@ _docker_events() { case "$cur" in -*) - COMPREPLY=( $( compgen -W "--filter -f --help --since --until" -- "$cur" ) ) + COMPREPLY=( $( compgen -W "--filter -f --help --since --until --format" -- "$cur" ) ) ;; esac } diff --git a/contrib/completion/fish/docker.fish b/contrib/completion/fish/docker.fish index 2ee367ff30..e72fb4e012 100644 --- a/contrib/completion/fish/docker.fish +++ b/contrib/completion/fish/docker.fish @@ -164,6 +164,7 @@ complete -c docker -A -f -n '__fish_seen_subcommand_from events' -s f -l filter complete -c docker -A -f -n '__fish_seen_subcommand_from events' -l help -d 'Print usage' complete -c docker -A -f -n '__fish_seen_subcommand_from events' -l since -d 'Show all events created since timestamp' complete -c docker -A -f -n '__fish_seen_subcommand_from events' -l until -d 'Stream events until this timestamp' +complete -c docker -A -f -n '__fish_seen_subcommand_from events' -l format -d 'Format the output using the given go template' # exec complete -c docker -f -n '__fish_docker_no_subcommand' -a exec -d 'Run a command in a running container' diff --git a/contrib/completion/zsh/_docker b/contrib/completion/zsh/_docker index ab9ba2d7c8..ff8952e7e0 100644 --- a/contrib/completion/zsh/_docker +++ b/contrib/completion/zsh/_docker @@ -1660,7 +1660,8 @@ __docker_subcommand() { $opts_help \ "($help)*"{-f=,--filter=}"[Filter values]:filter:__docker_complete_events_filter" \ "($help)--since=[Events created since this timestamp]:timestamp: " \ - "($help)--until=[Events created until this timestamp]:timestamp: " && ret=0 + "($help)--until=[Events created until this timestamp]:timestamp: " \ + "($help)--format=[Format the output using the given go template]:template: " && ret=0 ;; (exec) local state diff --git a/docs/reference/commandline/events.md b/docs/reference/commandline/events.md index 1900d09c2b..789bb57ffb 100644 --- a/docs/reference/commandline/events.md +++ b/docs/reference/commandline/events.md @@ -17,6 +17,7 @@ Get real time events from the server Options: -f, --filter value Filter output based on conditions provided (default []) + --format string Format the output using the given go template --help Print usage --since string Show all events created since timestamp --until string Stream events until this timestamp @@ -85,6 +86,16 @@ The currently supported filters are: * network (`network=`) * daemon (`daemon=`) +## Format + +If a format (`--format`) is specified, the given template will be executed +instead of the default +format. Go's [text/template](http://golang.org/pkg/text/template/) package +describes all the details of the format. + +If a format is set to `{{json .}}`, the events are streamed as valid JSON +Lines. For information about JSON Lines, please refer to http://jsonlines.org/ . + ## Examples You'll need two shells for this example. @@ -180,3 +191,22 @@ relative to the current time on the client machine: $ docker events --filter 'type=plugin' (experimental) 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/no-remove:latest) 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/no-remove:latest) + +**Format:** + + $ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' + Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + +**Format (as JSON Lines):** + + $ docker events --format '{{json .}}' + {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. + {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. + {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. diff --git a/man/docker-events.1.md b/man/docker-events.1.md index 4e38b53687..311020f6ef 100644 --- a/man/docker-events.1.md +++ b/man/docker-events.1.md @@ -10,6 +10,7 @@ docker-events - Get real time events from the server [**-f**|**--filter**[=*[]*]] [**--since**[=*SINCE*]] [**--until**[=*UNTIL*]] +[**--format**[=*FORMAT*]] # DESCRIPTION @@ -45,6 +46,9 @@ Docker networks report the following events: **--until**="" Stream events until this timestamp +**--format**="" + Format the output using the given go template + The `--since` and `--until` parameters can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the client machine's time. If you do not provide the `--since` option, @@ -96,6 +100,31 @@ relative to the current time on the client machine: If you do not provide the --since option, the command returns only new and/or live events. +## Format + +If a format (`--format`) is specified, the given template will be executed +instead of the default format. Go's **text/template** package describes all the +details of the format. + + # docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' + Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + +If a format is set to `{{json .}}`, the events are streamed as valid JSON +Lines. For information about JSON Lines, please refer to http://jsonlines.org/ . + + # docker events --format '{{json .}}' + {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. + {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. + {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + + # HISTORY April 2014, Originally compiled by William Henry (whenry at redhat dot com) based on docker.com source material and internal work.