docker eventsコマンドの使い方(実例付)CE対応


 docker eventsコマンドの使い方の紹介ページです。Docker CE ver17.12.1に対応しております。

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

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

 それでは以下で詳細に解説いたします。

 

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

フォーマット

docker events [オプション]

 

主なオプション一覧

-f, --filter=[] 指定したフィルター設定に基づいて内容をフィルタリングして出力する

--since=""
指定した時刻以降に発生したイベントを出力する

-- until=""
指定した時刻までに発生したイベントを出力する

 

■ 本記事の目次に戻る ■

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

 以下の実例は、Apacheの公式イメージにより起動したコンテナ(testvm)を使用します。コンテナは「docker run -d --name testvm httpd」で起動します。

 

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

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

$ 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 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (image=httpd, name=testvm)
2016-10-17T15:40:29.054709524+09:00 network connect 267ad2bbfe19cb38cf4428066ca1dad7b2b50e0c3e5f4e221402d4c975e0bce1 (container=acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109, name=bridge, type=bridge)
2016-10-17T15:40:29.193204943+09:00 container start acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (image=httpd, name=testvm)
2016-10-17T15:40:42.492841681+09:00 container kill acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (image=httpd, name=testvm, signal=15)
2016-10-17T15:40:42.530362548+09:00 container die acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (exitCode=0, image=httpd, name=testvm)
2016-10-17T15:40:42.573016839+09:00 network disconnect 267ad2bbfe19cb38cf4428066ca1dad7b2b50e0c3e5f4e221402d4c975e0bce1 (container=acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109, name=bridge, type=bridge)
2016-10-17T15:40:42.617211637+09:00 container stop acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (image=httpd, name=testvm)

 1行ごとに1つのイベントが出力されてます。フォーマットは以下の通りです。

<発生時刻> <カテゴリ> <イベント> <対象の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 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (image=httpd, name=testvm, signal=15)
2016-10-17T15:40:42.530362548+09:00 container die acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (exitCode=0, image=httpd, name=testvm)
2016-10-17T15:40:42.573016839+09:00 network disconnect 267ad2bbfe19cb38cf4428066ca1dad7b2b50e0c3e5f4e221402d4c975e0bce1 (container=acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109, name=bridge, type=bridge)
2016-10-17T15:40:42.617211637+09:00 container stop acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (image=httpd, name=testvm)

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

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

$ docker events --since "50m"

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

 

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

 「--since」オプションで時刻を指定すると、指定した時刻以降のイベントが出力されますが、「--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 acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (image=httpd, name=testvm)
2016-10-17T15:40:29.054709524+09:00 network connect 267ad2bbfe19cb38cf4428066ca1dad7b2b50e0c3e5f4e221402d4c975e0bce1 (container=acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109, name=bridge, type=bridge)
2016-10-17T15:40:29.193204943+09:00 container start acce5978f49f3e39f68331c4edd3f84721e533ada98ecc070d231c7bb4b23109 (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コマンドでサポートされているフィルターは以下の通りです。

コンフィグ( config=<名前か ID> )
コンテナ( container=<名前か ID> )
デーモン( daemon=<名前か ID> )
イベント( event=<イベント・タイプ> )
イメージ( image=<タグか ID> )
ラベル( label=<key> または label=<key>=<value> )
ネットワーク( network=<名前か ID> )
ノード( node=<ID> )
プラグイン( plugin=<名前か ID> )
スコープ( scope=<local か swarm> )
シークレット( secret=<名前か ID> )
サービス( service=<名前か ID> )
タイプ ( type=<container か image, volume, network, daemon, plugin, service, node, secret, config> )
ボリューム( volume=<名前> )

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

 

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

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

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

 また、同じキーと異なるキーが混在したフィルターを指定した際の仕様についても記載がありませんでした。これについて何か情報がありましたら、コメントいただけるとうれしいです!

 

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

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

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

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


コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください