Tomcatのアクセスログを出力する

Tomcatのアクセスログを出力する方法を取り上げますTomcatのアクセスログを出力する場合は、AccessLog出力用のValveタグを設定します。Valve要素はEngine要素・Host要素・Context要素のいずれかの子要素として設定します。

それぞれ以下のように適用範囲が異なります。
Engine要素…Tomcatエンジン全体
Host要素…Tomcatエンジン内に設定した仮想ホスト
Context要素…コンテキスト

例
<Valve className="org.apache.catalina.valves.AccessLogValve"
directory="logs" prefix="access_log." suffix=".txt"
pattern="common" resolveHosts="false"
rotatable="true" fileDateFormat="yyyy-MM-dd" />

実はデフォルトのservlet.xmlでは、コメントアウトされてはいるものの初めから記述されています。記述方法・記述場所などはこれを参考にするといいでしょう。


Valve要素にいくつかの属性を指定するのですが、classNameだけは必須で、用意されている基本的なアクセスログ出力の機能を使用する場合には「org.apache.catalina.valves.AccessLogValve」を指定します。W3Cによって定義された拡張ログファイル形式をサポートする「拡張アクセスログバルブ」を使用する場合には「org.apache.catalina.valves.ExtendedAccessLogValve」を指定します(※6.0以前の公式のリファレンスではなぜかExtendedAccessLogValveの記述がありませんが、5.5でも6.0でもExtendedAccessLogValveのクラスはあります)。

また自分で拡張したクラスを指定することも出来ます。しかし一般的には既存のAccessLogValveの機能で十分だと思います。そのためこのページでは、AccessLogValveについてのみ取り上げます。

directory, prefix, suffix, rotatable, fileDateFormatは、大雑把にまとめるとファイル名に関する設定になります。大概の人が直感的に理解できると思いますので、簡単な説明にとどめておきます。directoryはログの出力先ディレクトリを指定します。相対パスで指定した場合は、$CATALINA_BASEが基準になります。prefix, suffixは、それぞれファイル名の前と後ろにつける文字です。

rotatableは, rotatableはファイルのローテートをするかどうかの指定です。これをfalseにするとfileDateFormatは指定していても無効になります。fileDateFormatはファイル名に付加する日時文字列です。DateFormatで指定できる形式でかつファイル名にできる文字列なら何でもOKのようです。たいていは「yyyyMMdd」等の日付を指定しますが、「yyMMdd_hhmmss」等と時分秒まで指定することも可能です(あまり使わないと思いますけど…)。

Valve要素の属性はTomcatのバージョンによって使える内容が異なる部分があります。新しいバージョンで追加されていたり、(下位互換の為属性自体は残しているものの機能としては)無効になっているものもあります。Valve要素の属性のバージョン間の違いを簡単にまとめました。

属性 5.5 6.0 7.0 省略時のデフォルト値 備考
className ○ ○ ○ - (省略不可) 省略不可。使用するValveクラスを指定する。
pattern ○ ○ ○ common ログの出力内容の指定。
directory ○ ○ ○ logs ログファイルの出力先ディレクトリ。絶対パスか相対パス。相対パスで指定した場合には、$CATALINA_BASEが基準。
prefix ○ ○ ○ access_log. (末尾にドットが入っています) ログファイル名の先頭に付加する文字列。
suffix ○ ○ ○ (空文字、0文字) ログファイル名の末尾に付加する文字列。
rotatable ○ ○ ○ true ログファイルのローテートを行うか。
fileDateFormat ○ ○ ○ yyyy-MM-dd ログファイルのローテートを行う場合にファイルに付加する日時文字列のフォーマット。
buffered - ○ ○ true ログ出力のバッファ化。しない理由が見当たらない。
encoding - ○ ○ 不定 (システムデフォルトの文字コード) ログの文字コード。
locale - - ○ 不定 (Javaプロセスのデフォルトロケール) ロケール。日時フォーマットが変わる。
requestAttributes Enabled - - ○ false Set to true to check for the existence of request attributes (typically set by the RemoteIpValve and similar) that should be used to override the values returned by the request for remote address, remote host, server port and protocol.
conditionIf - - ○ - (なし) 条件付ロギング。指定したServletRequestのAttributeがnullでは無い場合にのみログを出力する。
conditionUnless - - ○ - (なし) 条件付ロギング。指定したServletRequestのAttributeがnullの場合にのみログを出力する。
condition ○ ○ △ - (なし) conditionUnlessと同じ。7.0以降では下位互換のため残している
resolveHosts ○ ○ × false 7.0以降では下位互換のため属性は残しているがサポートしていない

個人的には、バージョン間で違いがある部分は重要ではない属性だと思っています。バージョン間で共通している属性だけをしっかりと把握しておけば十分だと思います。特定のバージョンでのみ使える属性を詳しく把握されたい方は、ページ末のリンク先の公式リファレンスを参照してください。

pattern

属性の中で最も重要なのが、ログの出力内容を指定するpatternです。この属性は、大きなカスタマイズが必要になることもある重要な部分です。しっかりと理解しておきたいところです。

「pattern」には出力形式を指定しますが、デフォルトではシンプルな「common」が使用されます。 「common」 を指定するとホスト名・処理日時・リクエスト内容・HTTPステータス・レスポンスサイズなどを出力します。参照元やUAなども出力したい場合には「combined」を指定します。これ以外にtomcatの処理時間・IP・セッションIDなどを含む独自のパターンを指定することも出来ます。%{xxx}xの形式の識別子を使うと、リクエストヘッダー・レスポンスヘッダー・クッキー・ServletRequestやHttpSessionのattributeの値を取得することができます。

識別子 意味(リファレンスの記述) 意訳
%a Remote IP address リモートIP(アクセス者のIP)
%A Local IP address ローカルIP(サーバのIP)こんなの使う？
%h Remote host name (or IP address if enableLookups for the connector is false) ★リモートホスト名かIPアドレス
%v Local server name ローカルサーバ名
%p Local port on which this request was received 要求を受信したローカルポート
%l Remote logical username from identd (always returns '-') Tomcatでは常に'-'。(他のWebサーバ等と共通の伝統的な形式として残している)
%u Remote user that was authenticated (if any), else '-' 認証されたリモートユーザ名
%H Request protocol リクエストプロトコル
%m Request method (GET, POST, etc.) リクエストメソッド
%U Requested URL path リクエストされたURL
%q Query string (prepended with a '?' if it exists) クエリ文字列
%r First line of the request (method and request URI) ★メソッドとURL(基本)
%s HTTP status code of the response ★HTTPステータスコード
%b Bytes sent, excluding HTTP headers, or '-' if zero ★(HTTPヘッダを除く)レスポンスサイズ(byte)
%B Bytes sent, excluding HTTP headers (HTTPヘッダを除く)レスポンスサイズ(byte)
%t Date and time, in Common Log Format ★日時
%D Time taken to process the request, in millis ★処理時間(msec)
%T Time taken to process the request, in seconds 処理時間(sec)
%S User session ID セッションID
%I Current request thread name (can compare later with stacktraces) スレッド名
%{xxx}i for incoming headers ★リクエストヘッダーの値
%{xxx}o for outgoing response headers レスポンスヘッダーの値
%{xxx}c for a specific cookie ★クッキーの値
%{xxx}r xxx is an attribute in the ServletRequest ServletRequestのattributeの値
%{xxx}s xxx is an attribute in the HttpSession HttpSessionのattributeの値 ※★付きはよく使いそうなもの

pattern指定例
(1)「pattern="common"」…「pattern='%h %l %u %t "%r" %s %b'」と等価
(2)「pattern="combined"」…「pattern='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'」と等価
(3)「pattern="%t %D '%r' %s %b"」…「受信日時 処理時間(msec) 'メソッド リクエストURL' HTTPステータス レスポンスサイズ(byte)」

出力例
(1)127.0.0.1 - - [16/Jan/2012:23:06:23 +0900] "GET /hoge/huga.do HTTP/1.1" 200 38
(2)127.0.0.1 - - [16/Jan/2012:23:08:31 +0900] "GET /hoge/huga.do HTTP/1.1" 200 4682 "http://localhost:8090/hoge/huga.do" "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)"
(3)[16/Jan/2012:23:12:41 +0900] 141 'GET /hoge/huga.do HTTP/1.1' 200 2499

公式リファレンス

5.5系：${TOMCAT_HOME}/webapps/tomcat-docs/config/valve.html
6.0系・7.0系：${TOMCAT_HOME}/webapps/docs/config/valve.html
Apache Tomcat 5.5 Configuration Reference - The Valve Component
Apache Tomcat 6.0 Configuration Reference - The Valve Component
Apache Tomcat 7.0 Configuration Reference - The Valve Component

余談

一般的なアクセスログとしての利用も可能ですが「どの処理が処理時間がかかるのか」「どの画面がバイト数が多いのか」などシステムの負荷具合のデータを取得することが可能になります。このあたりの用途で使用することが特に有効ではないかと思います。