docker eventsコマンドの使い方（実例で解説）

　本記事はDocker ver24.0.7の環境で確認しています。

　docker eventsコマンドは、dockerデーモン内で発生したイベントを取得して、そのサマリー情報を出力することが可能です。

　取得可能なイベントは、コンテナの場合はstart、stop、createなど、Dockerイメージの場合はpull、delete、importなどがあります。

docker eventsコマンドのフォーマットとオプション

フォーマット

docker events [オプション]

主なオプション一覧

オプション	概説
-f, --filter=[]	指定したフィルター設定に基づいて内容をフィル タリングして出力する
--since=""	指定した時刻以降に発生したイベントを出力する
--until=""	指定した時刻までに発生したイベントを出力する

コマンド例

$ docker events

$ docker events --since "2016-10-17T15:40:40"

$ docker events --until "2016-10-17T15:40:40"

docker eventsコマンドの主な使い方

　以下で実例をまじえたコマンドの使い方を解説していきたいと思います。

基本事項の解説

　Docker環境では様々なイベントが発生しています。

　例えば、Dockerイメージをダウンロード（pull）したり削除（delete）したり、コンテナを停止（stop）したり強制終了（kill）したり、と色々なイベントがあります。

　また、コンテナを起動（start）しますと、表向きはコンテナをstartさせただけですが、裏ではDockerネットワークへの接続も行っています。

　普段意識していないことを可視化させるのも、docker eventsコマンドの役割です。

発生したイベントをリアルタイムに出力する

　以下のコマンドを実行しますと、それ以降で発生したイベントがリアルタイムに出力されます。

$ docker events

　イベントが発生すると出力され、発生していない時は待ち状態（プロンプトが戻らない）になります。

　終了する場合は「Ctrl+c」です。

　イベントを出力させるために、docker eventsコマンドを実行したターミナルとは別のターミナルを起動して、以下のコマンドを実行します。

$ docker run -d --name testvm httpd
$ docker stop testvm

　docker eventsコマンドを実行したターミナルには、以下の内容が出力されました。

2016-10-17T15:40:29.003873497+09:00 container create
 cce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231
c7bb4b23109 (image=httpd, name=testvm)
2016-10-17T15:40:29.054709524+09:00 network connect 
 267ad2bbfe19cb38cf4428066ca1dad7b2b50e0c3e5f4e22140
2d4c975e0bce1 (container=acce5978f49f3e39f68331c4edd
3f84721e533ada
98ecc070d231c7bb4b23109, name=bridge, type=bridge)
2016-10-17T15:40:29.193204943+09:00 container start 
 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d2
31c7bb4b23109 (image=httpd, name=testvm)
2016-10-17T15:40:42.492841681+09:00 container kill 
 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d2
31c7bb4b23109 (image=httpd, name=testvm, signal=15)
2016-10-17T15:40:42.530362548+09:00 container die 
 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d2
31c7bb4b23109 (exitCode=0, image=httpd, name=testvm)
2016-10-17T15:40:42.573016839+09:00 network disconnect
 267ad2bbfe19cb38cf4428066ca1dad7b2b50e0c3e5f4e221402
d4c975e0bce1 (container=acce5978f49f3e39f68331c4edd3f84721e533ada9
8ecc070d231c7bb4b23109, name=bridge, type=bridge)
2016-10-17T15:40:42.617211637+09:00 container stop 
 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d2
31c7bb4b23109 (image=httpd, name=testvm)

　１行ごとに１つのイベントが出力されてます。

　フォーマットは以下の通りです。

<発生時刻> <カテゴリ> <イベント> <対象のID> <（追加情報）>

　<発生時刻>は、各イベントの発生時刻がRFC3339の形式にて出力されます。

　<カテゴリ>は、イベントの発生元のコンポーネントで、containerやimage、plugin、volume、network、daemonなどがあります

　<イベント>は、start、stop、createなど、上の各カテゴリで発生した事象が出力されます。

　<対象のID>は、カテゴリがcontainer（コンテナ）であれば、対象のコンテナIDが、network（ネットワーク）であれば、対象のネットワークIDが、というように対象カテゴリのIDが出力されます。

　<（追加情報）>には、各イベント毎の補足情報が出力されます。例えば、コンテナがcreate（生成）された場合は、使用イメージ名およびコンテナ名が出力されます。

指定した時刻以降のイベントを出力する

　オプションを指定しない場合は、docker eventsコマンドを実行した時以降のイベントが出力されますが、「--since」オプションで時刻を指定すると、その指定した時刻までさかのぼって、その時刻以降のイベントが出力されます。

　時刻を指定する場合、時分秒が一桁の場合は0を補って指定してください。（例：×3、○03）

　時刻の指定は、RFC3339形式やUNIXタイムスタンプで特定の時刻を指定する方法、「2h30m」や「50s」などのように、現時点からさかのぼる時間を指定する方法があります。

　例えば現在、前項「発生したイベントをリアルタイムに出力する」の内容のイベントが発生していたとします。

　その状態で以下のコマンドを実行します。

$ docker events --since "2016-10-17T15:40:40"

　「--since」オプションで、2016年10月17日15時40分40秒以降のイベントを出力するように指定したことになります。

　コマンドを実行した結果、以下の内容が出力されて、イベント出力待ち状態になりました。

2016-10-17T15:40:42.492841681+09:00 container kill 
 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d
231c7bb4b23109 (image=httpd, name=testvm, signal=15)
2016-10-17T15:40:42.530362548+09:00 container die 
 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d
231c7bb4b23109 (exitCode=0, image=httpd, name=testvm)
2016-10-17T15:40:42.573016839+09:00 network disconnect
 267ad2bbfe19cb38cf4428066ca1dad7b2b50e0c3e5f4e22140
2d4c975e0bce1 (container=acce5978f49f3e39f68331c4edd
3f84721e533ada98ecc070d231c7bb4b23109, name=bridge, 
type=bridge)
2016-10-17T15:40:42.617211637+09:00 container stop 
 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d2
31c7bb4b23109 (image=httpd, name=testvm)

　2016年10月17日15時40分40秒以前のイベントは出力されていないことがわかります。

　また、以下のように「--since」オプションの指定をすることも可能です。

$ docker events --since "50m"

　これは、コマンドを実行した時点から50分前以降のイベントを出力するための指定です。

指定した時刻までのイベントを出力する

　「--until」オプションで時刻を指定した場合、指定した時刻までのイベントが出力されます。

　指定可能な形式は「--since」オプションと同様で、RFC3339形式やUNIXタイムスタンプで特定の時刻を指定する方法、「2h30m」や「50s」などのように、現時点からさかのぼる時間を指定する方法があります。

　「--since」オプションと同じコマンドで試してみます。

　「since」と「until」が異なるだけで、他は同じです。

$ docker events --until "2016-10-17T15:40:40"

　今度は以下の内容が出力されました。

2016-10-17T15:40:29.003873497+09:00 container create 
acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231
c7bb4b23109 (image=httpd, name=testvm)
2016-10-17T15:40:29.054709524+09:00 network connect 
 267ad2bbfe19cb38cf4428066ca1dad7b2b50e0c3e5f4e221402
d4c975e0bce1 (container=acce5978f49f3e39f68331c4edd3f84721e533ada9
8ecc070d231c7bb4b23109, name=bridge, type=bridge)
2016-10-17T15:40:29.193204943+09:00 container start 
 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d23
1c7bb4b23109 (image=httpd, name=testvm)

　「--since」オプションを指定した時は出力されていた2016年10月17日15時40分42秒のイベントは出力されず、2016年10月17日15時40分29秒に発生したイベントが出力されました。

　また、イベント出力待ち状態にならずに、docker eventsコマンドの処理が終了して、プロンプトが戻ってきました。

　このように、「--until」オプションで時刻を指定した場合、指定した時刻までのイベントを出力して、コマンドの処理が終了します。

　試しに、「--until」オプションで、未来の時刻を指定して実行してみたところ、イベント出力待ち状態になりました。

　そして、指定した時刻になったら、docker eventsコマンドが終了して、プロンプトが戻ってきました。

イベントをフィルタリングして出力する

　デフォルトでは全てのイベントが出力されますが、フィルターオプションを使用することで、特定のイベントのみ出力することが出来ます。

　フィルターは以下のフォーマットで指定します。

<キー>=<値>

　例えば、container=testvmのように指定します。

　以下のコマンドを実行すると、コンテナ名がtestvmのイベントのみが出力されます。

$ docker events --filter container=testvm

　複数のフィルターを指定することが可能です。

　次の例は、コンテナ名がtestvmでstopイベントのみ出力します。

$ docker events --filter container=testvm --filter event=stop

　上の例のように、キーが異なるフィルターを複数指定した場合は、AND条件として扱われます。

　今度は、次の例のように、同じキーのフィルターを複数指定します。

$ docker events --filter container=testvm --filter container=httptest

　同じキーを指定した場合はOR条件として扱われます。

　この場合は、コンテナ名がtestvmとhttptestのイベントが出力されます。

　docker eventsコマンドでサポートされているフィルターは以下の通りです。

「Docker公式ドキュメント　コマンドライン・リファレンス　docker events」より引用

　余談ですが、フィルターでコンテナ名を指定した場合、検索されるイベントは、コンテナ名の前方一致として検索されるようです。

　例えば、「container=testvm」とフィルターを指定した場合、testvm2やtestvmhttpなどの名前のコンテナのイベントも出力されました。

　でも、pretestvmなどの名前のコンテナのイベントは出力されませんでした。

　この仕様に関しましては、Docker公式ドキュメントで記載が見当たらなかったため、不確定情報としてご承知ください。

　また、同じキーと異なるキーが混在したフィルターを指定した際の仕様についても記載がありませんでした。

おわりに

 　以上でdocker eventsコマンドの紹介を終わります。

　ご指摘、ご要望などが御座いましたらコメントいただけるとうれしいです。

　他のDockerコマンドの実例付紹介記事は、本サイト内の別記事「Dockerのコマンドの一覧（オリジナルな実例付き）」をご参照ください。

　ご訪問ありがとうございました！