mod_log_config
サーバへのリクエストのロギング
Base
mod_log_config.c
log_config_module

このモジュールはクライアントのリクエストを柔軟にログ収集する機能を 提供します。ログはカスタマイズ可能な書式で書かれ、ファイルに直接 書いたり、外部プログラムに渡したりすることができます。個々のリクエストを 特徴に応じてログに書いたり書かなかったりできるように、条件による ログ収集も提供されています。

このモジュールは三つのディレクティブ提供します: ログファイルを作成するための TransferLog, 新しい書式を 定義する LogFormat, ログファイルと 書式を一度に定義する CustomLog です。 各リクエストが複数回ログ収集されるようにするために TransferLog ディレクティブと CustomLog ディレクティブは複数回使用することができます。

Apache ログファイル

# カスタムログ書式

LogFormat ディレクティブと CustomLog ディレクティブの書式を指定する引数は文字列です。この文字列を使ってそれぞれの リクエストがログファイルにログ収集されます。その文字列には ログファイルにそのまま 書かれる文字列や、それぞれ改行とタブを表す C 言語 形式の制御文字 "\n" と "\t" とを含めることができます。そのまま出力させたい引用符とバックスラッシュは バックスラッシュでエスケープする必要があります。

リクエストの特徴そのものは "`%`" ディレクティブを書式の文字列に書くことで ログ収集されます。"%" ディレクティブはログファイル中では以下のような 値で置換されます:

フォーマット文字列 | 説明
--- | ---
`%%` | パーセント記号
`%a` | リモート IP アドレス
`%A` | ローカル IP アドレス
`%B` | レスポンスのバイト数。HTTP ヘッダは除く。
`%b` | レスポンスのバイト数。HTTP ヘッダは除く。CLF 書式。 すなわち、1 バイトも送られなかったときは 0 ではなく、 '`-`' になる
`%{Foobar}C` | サーバに送られたリクエスト中のクッキー Foobar の値
`%D` | リクエストを処理するのにかかった時間、マイクロ秒単位
`%{FOOBAR}e` | 環境変数 FOOBAR の内容
`%f` | ファイル名
`%h` | リモートホスト
`%H` | リクエストプロトコル
`%{Foobar}i` | サーバに送られたリクエストの `Foobar:` ヘッダの内容
`%l` | (identd からもし提供されていれば) リモートログ名。 これは mod_ident がサーバに存在して、 IdentityCheck ディレクティブが `On` に設定されていない限り、 `-` になります。
`%m` | リクエストメソッド
`%{Foobar}n` | 他のモジュールからのメモ Foobar の内容
`%{Foobar}o` | 応答の `Foobar:` ヘッダの内容
`%p` | リクエストを扱っているサーバの正式なポート
`%{format}p` | サーバがリクエストを処理しているポートの公式 canonical のポート番号か、 サーバの実際のポート番号か、クライアント側の実際のポート番号かです。 format に使える文字列は `canonical`, `local`, `remote` になります。
`%P` | リクエストを扱った子プロセスのプロセス ID
`%{format}P` | リクエストを扱ったワーカーのプロセス ID かスレッド ID。 format として有効な値は `pid`, `tid`, `hextid` です。`hextid` を使うには APR 1.2.0 以降が必要です。
`%q` | 問い合せ文字列 (存在する場合は前に `?` が追加される。 そうでない場合は空文字列)
`%r` | リクエストの最初の行
`%s` | ステータス。内部でリダイレクトされたリクエストは、元々の リクエストのステータス --- 最後のステータスは `%>s`
`%t` | リクエストを受付けた時刻。 CLF の時刻の書式 (標準の英語の書式)
`%{format}t` | format で与えられた書式による時刻。format は `strftime (3)` の 書式である必要がある。(地域化されている可能性がある)
`%T` | リクエストを扱うのにかかった時間、秒単位
`%u` | リモートユーザ (認証によるもの。ステータス (`%s`) が 401 のときは意味がないものである可能性がある)
`%U` | リクエストされた URL パス。クエリ文字列は含まない
`%v` | リクエストを扱っているサーバの正式な ServerName
`%V` | UseCanonicalName の設定によるサーバ名

`%X`

応答が完了したときの接続ステータス:

`X` = | 応答が完了する前に接続が異常終了
`+` = | 応答が送られた後に接続を持続することが可能
`-` = | 応答が送られた後に接続が切られる

(このディレクティブは Apache 1.3 の後期のバージョンでは `%c` に割り当てられて いましたが、これは歴史的に ssl が使用している `%{var}c` 構文と衝突していました。)

`%I` | リクエストとヘッダを含む、受け取ったバイト数。 0 にはならない。 これを使用するためには mod_logio が必要
`%O` | ヘッダを含む、送信したバイト数。0 にはならない。 これを使用するためには mod_logio が必要

## 修飾子

特定の要素は "%" の直後に HTTP ステータスコードをカンマ区切りで 指定することで、表示を制限することができます。例えば `"%400,501{User-agent}i"` では、 400 と 500 番エラーでのみ `User-agent` をログします。 他のステータスコードでは `"-"` という文字列が ログされます。ステータスコードのリストは "`!`" で否定を指定することができます : `"%!200,304,302{Referer}i"` は、指定された 3 つのコードのどれにも該当しないリクエスト全てで `Referer` をログします。

修飾子 "<" と ">" は内部リダイレクトされたリクエストのログに 元のリクエストか最終的なリクエストのどちらを使用するかを 指定するために使います。デフォルトでは、`%` ディレクティブの `%s, %U, %T, %D, %r` は元のリクエストを、他は最終的なリクエストを 使用します。例えば、リクエストの最終ステータスを記録するには `%>s` を、内部的に認証されていないリソースへリダイレクトされた リクエストで元のリクエストで認証されたユーザを記録するためには `%<u` を使うことができます。

## その他注意点

セキュリティ上の理由により 2.0.46 より、 `%r`, `%i`, `%o` に入っている、 印字不可能な文字と他の特別な文字は、`\xhh` という形式の文字列でエスケープされるようになりました。hh は そのままのバイトの値の 16 進での値です。この規則の例外には、 バックスラッシュを使ってエスケープされる `"` と `\` と、 C 形式の表記法が使われる空白文字 (`\n`, `\t` など) があります。2.0.46 以前のバージョンではエスケープ処理は行われませんので、 生ログファイルを扱う際に注意が必要です。

httpd 2.0 では 1.3 とは異なり、`%b` と `%B` フォーマット文字列はクライアントに送信されたバイト数そのものではなく、 HTTP レスポンスのバイト数です (これらは異なるもので、たとえば、 コネクションが途中で破棄された場合や、SSL 使用時に一致しません) 。 mod_logio で提供されている `%O` フォーマット文字列で、ネットワーク経由で実際に転送されたバイト数を 記録できます。

## 例

よく使われるフォーマット文字列は:

Common Log Format (CLF)
  `"%h %l %u %t \"%r\" %>s %b"`
バーチャルホスト付き Common Log Format
  `"%v %h %l %u %t \"%r\" %>s %b"`
NCSA extended/combined ログ書式
  `"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""`
Referer ログ書式
  `"%{Referer}i -> %U"`
Agent (ブラウザ) ログ書式
  `"%{User-agent}i"`

# セキュリティに関して

ログファイルが保存されているディレクトリがサーバを起動した以外のユーザで 書き込み可能なときにセキュリティの問題が発生する理由の詳細はセキュリティのこつ を参照してください。

BufferedLogs
ディスクに書き出す前にメモリにログエントリをバッファする
BufferedLogs On|Off
BufferedLogs Off
server config
Experimental
2.0.41 以降

BufferedLogs ディレクティブを使うと mod_log_config の挙動が変化して、 複数のログを書き出す際に、それぞれのリクエスト処理後毎に 書き出すのではなく、いったんメモリに蓄えてから、 まとめてディスクに書き出すようになります。 この結果ディスクアクセスがより効率的になり、 高いパフォーマンスの得られるシステムもあるでしょう。 このディレクティブはサーバ全体で一度だけ設定できます; バーチャルホストごとに設定することはできません。

このディレクティブは実験的なものですので、 使用する際は注意してください。

CustomLog
ログファイルの名前と書式を設定する
CustomLog file|pipe format|nickname [env=[!]environment-variable]
server config
virtual host

CustomLog ディレクティブはサーバへのリクエストを ログ収集するために使われます。ログの書式が指定され、 環境変数を使ってロギングが条件に応じて行なわれるようにすることもできます。

ログが書かれる場所を指定する最初の引数は以下の二つの形式の値を とることができます:

file
  ServerRoot
  からの相対パスで表されるファイル名。
pipe
  パイプ文字 "`|`" と、その後に標準入力からログの 情報を受けとるプログラムへのパスが続いたもの。

  # セキュリティ

  もしプログラムが使用された場合、 httpd が起動されたユーザとして実行されます。これはサーバが root によって起動された場合は root になります。プログラムが 安全であるように留意してください。

  # 注

  Unix でないプラットフォームでファイルのパスを入力しているときは、 使用しているプラットフォームがバックスラッシュの使用を許可していた として、通常のスラッシュだけを使うように気をつけてください。 一般的に、設定ファイル中では常に普通のスラッシュのみを使うようにする 方が良いです。

二つめの引数はログファイルに何が書かれるかを指定します。 前にある LogFormat ディレクティブにより 定義された nickname か、ログの書式 のところで説明されている、明示的な format 文字列の どちらかを指定することができます。

例えば、以下の二つのディレクティブ群は全く同じ効果をもたらします:

# CustomLog with format nickname
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
# CustomLog with explicit format string
CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"

三つ目の引数は省略可能で、サーバの環境にある変数があるかないかに 応じてリクエストをログ収集するかどうかを制御するために使うことができます。 指定された環境変数がリクエストに対して 設定されていた場合 ('`env=!name`' 文が使われたときは 設定されていない場合)、リクエストがログ収集されます。

環境変数は mod_setenvif モジュールと mod_rewrite モジュールの両方もしくは 片方を用いてリクエストごとに設定することができます。 例えば、サーバにあるすべての GIF 画像へのリクエストを別のログファイル には記録したいけれど、メインログには記録したくない、というときは 以下のものを使うことができます:

SetEnvIf Request_URI \.gif$ gif-image
CustomLog gif-requests.log common env=gif-image
CustomLog nongif-requests.log common env=!gif-image

古い RefererIgnore ディレクティブと同じ挙動をさせたい場合は、 次のようにします:

SetEnvIf Referer example\.com localreferer
CustomLog referer.log referer env=!localreferer
LogFormat
ログファイルで使用する書式を設定する
LogFormat format|nickname [nickname]
LogFormat "%h %l %u %t \"%r\" %>s %b"
server config
virtual host

このディレクティブはアクセスログファイルの書式を指定します。

LogFormat ディレクティブは二つの形式のどちらかを とることができます。最初の形式では一つの引数のみが指定され、 続く TransferLog で指定されたログで使われるログの書式を設定します。この単独の引数では 上のカスタムログ書式で説明されているように format を明示的に指定することができます。 もしくは、下で説明されているように前に LogFormat ディレクティブで定義されたログの書式を nicknameを使って 参照することもできます。

LogFormat ディレクティブの二つめの形式は format に nickname を与えます。 フォーマット文字列全体を再び書くかわりに、 この nickname を続きの LogFormat ディレクティブや CustomLog ディレクティブで使うことができます。 Nickname を定義する LogFormat ディレクティブは 他には何もしません -- すなわち、ニックネームを定義 するだけで、実際に書式を適用してデフォルトにするということは行ないません。 ですから、これは続く TransferLog ディレクティブには影響を与えません。 さらに、LogFormat ディレクティブは既存の nickname を 使って別の nickname を定義することはできません。Nickname には パーセント記号 (`%`) が含まれていてはいけないことにも注意 してください。

# 例

LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common
TransferLog
ログファイルの位置を指定
TransferLog file|pipe
server config
virtual host

このディレクティブは、ログ書式を直接指定できないことと、 条件付きロギングが無いことを除くと、CustomLog と全く同じ引数と効果があります。 直接ログ書式を指定する代わりに、ログの書式はそこまでで一番最後に指定された ニックネームを定義しない LogFormat ディレクティブ で定義されたものを使います。 もし他の書式が全く指定されていないときは Common Log Format が使われます。

# 例

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log