log

HTTPリクエストのログ記録（アクセスログとも呼ばれます）を有効にし、構成します。

logディレクティブは、hostnamesサブディレクティブで上書きされない限り、表示されるサイトブロックのホスト名に適用されます。

構成されている場合、デフォルトではサイトへのすべてのリクエストがログに記録されます。一部のリクエストをログ記録から条件付きでスキップするには、skip_logディレクティブを使用します。

• 構文
• 出力モジュール
  • stderr
  • stdout
  • discard
  • file
  • net
• フォーマットモジュール
  • console
  • json
  • filter
    • delete
    • rename
    • replace
    • ip_mask
    • query
    • cookie
    • regexp
    • hash
• 例

Caddy v2.5以降、デフォルトでは、機密情報が含まれる可能性のあるヘッダー（Cookie、Set-Cookie、Authorization、Proxy-Authorization）は空の値でログに記録されます。この動作は、log_credentialsグローバルサーバーオプションで無効にできます。

構文

log [<logger_name>] {
	hostnames <hostnames...>
	output <writer_module> ...
	format <encoder_module> ...
	level  <level>
}

• logger_nameは、このサイトのロガー名を上書きするオプションです。

  デフォルトでは、ロガー名は自動的に生成されます。たとえば、Caddyfile内のサイトの順序に応じて、log0、log1などが生成されます。これは、グローバルオプションで定義された別のロガーからこのロガーの出力を確実に参照する場合にのみ役立ちます。以下の例を参照してください。

• hostnamesは、このロガーが適用されるホスト名を上書きするオプションです。

  デフォルトでは、ロガーはそれが表示されるサイトブロックのホスト名、つまりサイトアドレスに適用されます。これは、ワイルドカードサイトブロックでサブドメインごとに異なるロガーを定義する場合に役立ちます。以下の例を参照してください。

• outputは、ログを書き込む場所を構成します。以下のoutputモジュールを参照してください。

  デフォルト：stderr。

• formatは、ログをエンコードまたはフォーマットする方法を記述します。以下のformatモジュールを参照してください。

  デフォルト：stderrがターミナルであると検出された場合はconsole、それ以外の場合はjson。

• levelは、ログに記録する最小エントリレベルです。デフォルト：INFO。

  アクセスログは現在、INFOとERRORレベルのログのみを出力することに注意してください。

出力モジュール

outputサブディレクティブを使用すると、ログの書き込み先をカスタマイズできます。

stderr

標準エラー（コンソール、デフォルトです）。

output stderr

stdout

標準出力（コンソール）。

output stdout

discard

出力なし。

output discard

file

ファイル。デフォルトでは、ログファイルはディスク容量の枯渇を防ぐためにローテーション（「ロール」）されます。

ログのロールは、lumberjack によって提供されます。

output file <filename> {
	roll_disabled
	roll_size     <size>
	roll_uncompressed
	roll_local_time
	roll_keep     <num>
	roll_keep_for <days>
}

• <filename>は、ログファイルへのパスです。

• roll_disabledは、ログのロールを無効にします。これにより、ディスク容量が枯渇する可能性があるため、ログファイルが他の方法で保守されている場合にのみ使用してください。

• roll_sizeは、ログファイルをロールするサイズです。現在の実装では、メガバイトの解像度をサポートしています。小数値は、次の整数メガバイトに切り上げられます。たとえば、1.1MiBは2MiBに切り上げられます。

  デフォルト：100MiB

• roll_uncompressedは、gzipログ圧縮をオフにします。

  デフォルト：gzip圧縮が有効になっています。

• roll_local_timeは、ファイル名にローカルタイムスタンプを使用するようにローリングを設定します。

  デフォルト：UTC時間を使用します。

• roll_keepは、最も古いものを削除する前に保持するログファイルの数です。

  デフォルト：10

• roll_keep_forは、ロールされたファイルを期間文字列として保持する期間です。現在の実装では、日の解像度をサポートしています。小数値は、次の整数日に切り上げられます。たとえば、36h（1.5日）は48h（2日）に切り上げられます。デフォルト：2160h（90日）

net

ネットワークソケット。ソケットがダウンすると、再接続を試みている間、ログがstderrに出力されます。

output net <address> {
	dial_timeout <duration>
	soft_start
}

• <address>は、ログを書き込むアドレスです。

• dial_timeoutは、ログソケットへの接続が成功するまで待機する時間です。ソケットがダウンした場合、ログの排出はこの時間までブロックされる可能性があります。

• soft_startは、ソケットへの接続時のエラーを無視し、リモートログサービスがダウンしている場合でも構成をロードできるようにします。代わりに、ログはstderrに出力されます。

フォーマットモジュール

formatサブディレクティブを使用すると、ログのエンコード（フォーマット）方法をカスタマイズできます。これは、logブロック内に表示されます。

各個別のエンコーダーの構文に加えて、これらの共通プロパティは、ほとんどのエンコーダーで設定できます。

format <encoder_module> {
	message_key     <key>
	level_key       <key>
	time_key        <key>
	name_key        <key>
	caller_key      <key>
	stacktrace_key  <key>
	line_ending     <char>
	time_format     <format>
	time_local
	duration_format <format>
	level_format    <format>
}

• message_keyログエントリのメッセージフィールドのキー。デフォルト：msg

• level_keyログエントリのレベルフィールドのキー。デフォルト：level

• time_keyログエントリのタイムフィールドのキー。デフォルト：ts

• name_keyログエントリの名前フィールドのキー。デフォルト：name

• caller_keyログエントリのcallerフィールドのキー。

• stacktrace_keyログエントリのstacktraceフィールドのキー。

• line_ending使用する行末。

• time_formatタイムスタンプの形式。

  デフォルト：形式がデフォルトでconsoleになっている場合はwall_milli、それ以外の場合はunix_seconds_float。

  次のいずれかになります

  • unix_seconds_float Unixエポックからの秒数の浮動小数点数。
  • unix_milli_float Unixエポックからのミリ秒数の浮動小数点数。
  • unix_nano Unixエポックからのナノ秒数の整数。
  • iso8601 例：2006-01-02T15:04:05.000Z0700
  • rfc3339 例：2006-01-02T15:04:05Z07:00
  • rfc3339_nano 例：2006-01-02T15:04:05.999999999Z07:00
  • wall 例：2006/01/02 15:04:05
  • wall_milli 例：2006/01/02 15:04:05.000
  • wall_nano 例：2006/01/02 15:04:05.000000000
  • common_log 例：02/Jan/2006:15:04:05 -0700
  • または、互換性のある任意のタイムレイアウト文字列。詳細については、Goドキュメントを参照してください。

  形式文字列の部分はレイアウトの特殊な定数であることに注意してください。したがって、2006は年、01は月、Janは文字列としての月、02は日です。形式文字列に実際の現在の日付番号を使用しないでください。

• time_localデフォルトのUTC時間ではなく、ローカルシステム時間でログを記録します。

• duration_format期間の形式。

  デフォルト：seconds。

  次のいずれかになります

  • seconds経過秒数の浮動小数点数。
  • nano経過ナノ秒数の整数。
  • string Goの組み込み文字列形式を使用します。たとえば、1m32.05sや6.31msなどです。

• level_formatレベルの形式。

  デフォルト：形式がデフォルトでconsoleになっている場合はcolor、それ以外の場合はlower。

  次のいずれかになります

  • lower小文字。
  • upper大文字。
  • color大文字、ANSIカラー付き。

console

コンソールエンコーダーは、構造を維持しながら、人間が読めるようにログエントリをフォーマットします。

format console

json

各ログエントリをJSONオブジェクトとしてフォーマットします。

format json

filter

別のエンコーダーモジュールをラップし、フィールドごとのフィルタリングを可能にします。

format filter {
	wrap <encode_module> ...
	fields {
		<field> <filter> ...
	}
}

ネストされたフィールドは、>でネストのレイヤーを表すことで参照できます。言い換えれば、{"a":{"b":0}}のようなオブジェクトの場合、内部フィールドはa>bとして参照できます。

次のフィールドはログの基本であり、基盤となるロギングライブラリによって特殊なケースとして追加されるため、フィルター処理できません：ts、level、logger、およびmsg。

これらが利用可能なフィルターです

delete

エンコードされないようにフィールドをマークします。

<field> delete

rename

ログフィールドのキーの名前を変更します。

<field> rename <key>

replace

エンコード時に指定された文字列に置き換えられるフィールドをマークします。

<field> replace <replacement>

ip_mask

CIDRマスク（つまり、IPの左側から保持するビット数）を使用して、フィールド内のIPアドレスをマスクします。フィールドが文字列の配列（HTTPヘッダーなど）の場合、配列内の各値がマスクされます。値は、コンマで区切られたIPアドレスの文字列にすることができます。

IPv4アドレスとIPv6アドレスでは、合計ビット数が異なるため、別々の構成があります。

ほとんどの場合、フィルター処理するフィールドは次のとおりです

• 直接接続しているクライアントの場合はrequest>remote_ip
• trusted_proxiesが構成されている場合は、解析された「実際のクライアント」の場合はrequest>client_ip
• リバースプロキシの背後にある場合はrequest>headers>X-Forwarded-For

<field> ip_mask {
	ipv4 <cidr>
	ipv6 <cidr>
}

query

URLフィールドのクエリ部分を操作するために、1つ以上のアクションを実行するフィールドをマークします。ほとんどの場合、フィルター処理するフィールドはrequest>uriです。

<field> query {
	delete  <key>
	replace <key> <replacement>
	hash    <key>
}

使用可能なアクションは次のとおりです

• deleteは、指定されたキーをクエリから削除します。

• replaceは、指定されたクエリキーの値をreplacementに置き換えます。リダクションプレースホルダーを挿入するのに便利です。URLにクエリキーがあったことはわかりますが、値は非表示になります。

• hashは、指定されたクエリキーの値を、値のSHA-256ハッシュの最初の4バイト（小文字の16進数）に置き換えます。各リクエストに異なる値があったかどうかを認識できるようにしながら、機密性が高い場合は値を隠すのに便利です。

cookie

CookieHTTPヘッダーの値を操作するために、1つ以上のアクションを実行するフィールドをマークします。ほとんどの場合、フィルター処理するフィールドはrequest>headers>Cookieです。

<field> cookie {
	delete  <name>
	replace <name> <replacement>
	hash    <name>
}

使用可能なアクションは次のとおりです

• deleteは、ヘッダーから名前で指定されたCookieを削除します。

• replace は、指定された Cookie の値を replacement で置き換えます。リダクションプレースホルダーを挿入するのに便利です。ヘッダーに Cookie があったことはわかりますが、値は隠されます。

• hash は、指定された Cookie の値を、その値の SHA-256 ハッシュの最初の 4 バイト（小文字の16進数）で置き換えます。値が機密情報である場合に、値を隠蔽しつつ、各リクエストで異なる値があったかどうかを確認するのに便利です。

同じ Cookie 名に対して複数のアクションが定義されている場合、最初のアクションのみが適用されます。

regexp

エンコード時に正規表現による置換を適用するフィールドを指定します。フィールドが文字列の配列（例：HTTPヘッダー）である場合、配列内の各値に置換が適用されます。

<field> regexp <pattern> <replacement>

使用される正規表現言語は、Go に含まれる RE2 です。 RE2 の構文リファレンス と Go の正規表現構文の概要 を参照してください。

置換文字列では、${group} でキャプチャグループを参照できます。group は、式のキャプチャグループの名前または番号です。キャプチャグループ 0 は正規表現全体のマッチ、1 は最初のキャプチャグループ、2 は 2 番目のキャプチャグループ、というように続きます。

hash

エンコード時に、フィールドをその値の SHA-256 ハッシュの最初の 4 バイト（8 文字の 16 進数）で置き換えるように指定します。フィールドが文字列配列（例：HTTP ヘッダー）である場合、配列内の各値がハッシュ化されます。

値が機密情報である場合に、値を隠蔽しつつ、各リクエストで異なる値があったかどうかを確認するのに便利です。

<field> hash

例

デフォルトのロガーへのアクセスログ記録を有効にします。

言い換えれば、デフォルトでは stderr にログが出力されますが、log グローバルオプションで default ロガーを再構成することで変更できます。

example.com {
	log
}

ファイルにログを書き込みます（ログローテーションはデフォルトで有効になっています）。

example.com {
	log {
		output file /var/log/access.log
	}
}

ログローテーションをカスタマイズします。

example.com {
	log {
		output file /var/log/access.log {
			roll_size 1gb
			roll_keep 5
			roll_keep_for 720h
		}
	}
}

ログから User-Agent リクエストヘッダーを削除します。

example.com {
	log {
		format filter {
			wrap console
			fields {
				request>headers>User-Agent delete
			}
		}
	}
}

複数の機密 Cookie をリダクションします。（一部の機密ヘッダーはデフォルトで空の値でログ記録されることに注意してください。Cookie ヘッダー値のログ記録を有効にするには、log_credentials グローバルオプションを参照してください）

example.com {
	log {
		format filter {
			wrap console
			fields {
				request>headers>Cookie cookie {
					replace session REDACTED
					delete secret
				}
			}
		}
	}
}

リクエストからのリモートアドレスをマスクします。IPv4 アドレスの場合は最初の 16 ビット（つまり 255.255.0.0）、IPv6 アドレスの場合は最初の 32 ビットを保持します。

Caddy v2.7 以降、remote_ip と client_ip の両方がログに記録されることに注意してください。client_ip は trusted_proxies が構成されている場合の「実際の IP」です。

example.com {
	log {
		format filter {
			wrap console
			fields {
				request>remote_ip ip_mask {
					ipv4 16
					ipv6 32
				}
			}
		}
	}
}

ワイルドカードサイトブロック内の各サブドメインに対して個別のログファイルを書き込むには、各ロガーの hostnames を上書きします。これは、繰り返しの記述を避けるためにスニペットを使用します。

(subdomain-log) {
	log {
		hostnames {args[0]}
		output file /var/log/{args[0]}.log
	}
}

*.example.com {
	import subdomain-log foo.example.com
	@foo host foo.example.com
	handle @foo {
		respond "foo"
	}

	import subdomain-log bar.example.com
	@bar host bar.example.com
	handle @bar {
		respond "bar"
	}
}

特定のサブドメインのアクセスログを、異なる形式（transform-encoder プラグイン を使用した形式と json を使用した形式）の2つの異なるファイルに書き込むには、次のようにします。

これは、サイトブロックでロガー名を foo として上書きし、include http.log.access.foo を使用して、グローバルオプションの 2 つのロガーにそのロガーによって生成されたアクセスログを含めることで機能します。

{
	log access-formatted {
		include http.log.access.foo
		output file /var/log/access-foo.log
		format transform "{common_log}"
	}

	log access-json {
		include http.log.access.foo
		output file /var/log/access-foo.json
		format json
	}
}

foo.example.com {
	log foo
}