ログドライバーの設定

読む時間の目安: 4 分

Docker にはログ出力のメカニズムが複数あるので、コンテナーまたはサービスのログ確認 を行うことができます。 このメカニズムのことをログドライバー(logging driver)と呼びます。 Docker デーモンにはデフォルトのログドライバーが設定されています。 別のログドライバーを利用するような設定を行わないかぎり、各コンテナーはこのデフォルトログドライバーを利用します。

デフォルトで Docker は json-fileログドライバー を利用します。 これはコンテナーログを JSON 形式として内部にキャッシュします。 Docker が提供するログドライバーの利用だけでなく、ログドライバープラグイン を導入して利用することもできます。

Tip: use the “local” logging driver to prevent disk-exhaustion

By default, no log-rotation is performed. As a result, log-files stored by the default json-file logging driver logging driver can cause a significant amount of disk space to be used for containers that generate much output, which can lead to disk space exhaustion.

Docker keeps the json-file logging driver (without log-rotation) as a default to remain backward compatibility with older versions of Docker, and for situations where Docker is used as runtime for Kubernetes.

For other situations, the “local” logging driver is recommended as it performs log-rotation by default, and uses a more efficient file format. Refer to the Configure the default logging driver section below to learn how to configure the “local” logging driver as a default, and the local file logging driver page for more details about the “local” logging driver.

デフォルトのログドライバー設定

特定のログドライバーを Docker デーモンのデフォルトとして設定するには、設定ファイルdaemon.jsonにおいてlog-driverにそのログドライバー名を指定します。 設定ファイルの詳細については dockerdリファレンスマニュアルdaemon.jsonの節を参照してください。

デフォルトのログドライバーはjson-fileです。 以下に示す例では、デフォルトのログドライバーを明示的にlocalに設定します。

{
  "log-driver": "local"
}

ログドライバーに設定変更可能なオプションがある場合、daemon.jsonファイル内においてlog-optsキーを使って JSON オブジェクトとして指定することができます。 以下の例は、ログドライバーjson-fileにおいて 4 つの設定オプションを指定します。

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3",
    "labels": "production_status",
    "env": "os,customer"
  }
}

新たに生成されたコンテナーの変更内容を有効にするために、Docker を再起動します。 既存のコンテナーは、この新たなログ設定は利用しません。

メモ

設定ファイルdaemon.json内のlog-optsオプションは文字列として指定する必要があります。 したがってブール値や数値(上の例でいうとmax-fileの設定値)はクォート(")で囲む必要があります。

ログドライバーを指定しなかった場合、デフォルトはjson-fileです。 Docker デーモンにおいて設定されている、その時点でのデフォルトのログドライバーが何であるかは、docker infoを実行してLogging Driverの項目を見ればわかります。 以下のコマンドは Linux、macOS、Windows 上の PowerShell において実行することができます。

$ docker info --format '{{.LoggingDriver}}'

json-file

メモ

デーモン設定においてデフォルトのログドライバーやそのオプションを変更した場合、その変更内容はそれ以降に生成されたコンテナーにのみ適用されます。 既存のコンテナーが利用するログドライバーオプションは、それが生成されたときのものがそのまま使われます。 コンテナーに対するログドライバーは更新するには、必要なオプションを使ってそのコンテナーを再生成する必要があります。 コンテナーにおけるログドライバー設定に関しては、以下に示す コンテナーに対するログドライバー設定 を参照してください。

コンテナーに対するログドライバー設定

コンテナーの起動時には、Docker デーモンのデフォルトとは異なる、別のログドライバーを設定することができます。 これは--log-driverフラグを使います。 ログドライバーに設定変更可能なオプションがある場合、--log-opt <NAME>=<VALUE>フラグを必要な分だけ用いて指定することができます。 コンテナーがデフォルトのログドライバーを利用しているとしても、設定変更可能なオプションはさまざまなものがあります。

以下の例は Alpine コンテナーの起動時に、ログドライバーとしてnoneを指定しています。

$ docker run -it --log-driver none alpine ash

デーモンがログドライバーjson-fileを利用している場合に、実行コンテナーに設定されているログドライバーが何であるかを確認するには、以下のようにdocker inspectを実行します。 実行にあたっては<CONTAINER>の部分をコンテナー名か、あるいはコンテナー ID とします。

$ docker inspect -f '{{.HostConfig.LogConfig.Type}}' <CONTAINER>

json-file

コンテナーからログドライバーへのメッセージ転送モードの設定

Docker には、コンテナーからログドライバーに向けてのログメッセージ転送に関して、2 つのモードがあります。

  • (デフォルト) コンテナーからドライバーへの直接のログメッセージ転送はブロックするモード。
  • ブロックしない(non-blocking)モード。 ドライバーが利用するものとして用意されている、各コンテナーごとの中間リングバッファーに、ログメッセージが保存されます。

non-blockingメッセージ転送モードの場合、ログ出力のためにアプリケーションに負荷がかかっても、ログメッセージを転送しません。 STDERR や STDOUT ストリームがブロックされると、アプリケーションが予期せずに失敗することがあります。

警告

バッファーがいっぱいになって、新たなメッセージがキューに待機するようになると、メモリ上にあるメッセージの中で最も古いものが破棄されます。アプリケーションのログ出力処理がブロックされることよりも、メッセージが破棄されることの方が良い場合もあります。

ログオプションのmodeは、メッセージ転送をブロックするblocking(デフォルト)か、ブロックしないnon-blockingかを制御します。

ログオプションmax-buffer-sizemodenon-blockingに設定されている場合に、中間的なメッセージ保存場所として利用されるリングバッファーのサイズを設定します。 max-buffer-sizeのデフォルトは 1 メガバイトです。

以下に示す例は Alpine コンテナーの起動にあたって、ログ出力を non-blocking モードとし、バッファーを 4 メガバイトとします。

$ docker run -it --log-opt mode=non-blocking --log-opt max-buffer-size=4m alpine ping 127.0.0.1

ログドライバーに対する環境変数やラベルの利用

ログドライバーの中には、コンテナーに対して指定された--env|-eフラグや--labelフラグの値を、コンテナーログに加えられるようになっているものがあります。 以下の例では、Docker デーモンがデフォルトのログドライバー(json-fileとします)を利用している状態でコンテナーを起動し、さらに環境変数os=ubuntuを設定します。

$ docker run -dit --label production_status=testing -e os=ubuntu alpine sh

ログドライバー側が対応していれば、ログ内に追加項目が出力されることになります。 以下の出力は、ログドライバーjson-fileによって生成されるものです。

"attrs":{"production_status":"testing","os":"ubuntu"}

サポートされるログドライバー

ログドライバーは以下に示すものがサポートされています。 ドライバーに対する設定可能オプションについては、リンク先にある各ドライバーのドキュメントを参照してください。 ログドライバープラグイン を利用している場合は、さらにオプションがあります。

ドライバー 内容説明
none コンテナーのログは出力されません。したがってdocker logsからは何も出力されません。
local 独自フォーマットによりログが保存されます。これは最小限のオーバーヘッドとなるように設計されています。
json-file ログは JSON 形式で出力されます。Docker におけるデフォルトのログドライバーです。
syslog ログメッセージをsyslogに出力します。ホストマシン上にsyslogデーモンを実行しておく必要があります。
journald ログメッセージをjournaldに出力します。ホストマシン上にjournaldデーモンを実行しておく必要があります。
gelf ログメッセージを Graylog や Logstash のような Graylog Extended Log Format (GELF) エンドポイントに出力します。
fluentd ログメッセージをfluentd(forward input) に出力します。ホストマシン上に fluentdデーモンを実行しておく必要があります。
awslogs ログメッセージを Amazon CloudWatch Logs へ出力します。
splunk ログメッセージを、HTTP Event Collector を使ってsplunkに出力します。
etwlogs ログメッセージを Event Tracing for Windows (ETW) イベントとして出力します。Windows プラットフォームにおいてのみ利用可能です。
gcplogs ログメッセージを Google Cloud Platform (GCP) Logging に出力します。
logentries ログメッセージを Rapid7 Logentries に出力します。

メモ

Docker Engine 19.03 またはそれ以前を利用している場合、docker logsコマンド は、ログドライバーlocaljson-filejournaldに対してのみ機能します。 Docker 20.10 またはそれ以降には「デュアルログ」(dual logging)機能が導入されています。 これはローカルバッファーを使って、どのようなログドライバーでもdocker logsコマンドが利用できるものです。 詳しくは リモートログドライバーを使ったログ読み込み を参照してください。

ログドライバーの制限事項

  • ログ情報を読むには、ローテートされるログファイルを伸張(解凍)することが必要になります。 その際には一時的にディスクを消費します(ローテートされたファイルからログを読み込むまで)。 また伸張(解凍)の際には CPU 使用が増加します。
  • Docker のデータディレクトリを収容するホストのストレージ容量によって、ログファイルの最大容量が定まります。
docker, logging, driver