path: root/docs/manual/mod/mod_log_config.xml.ja

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
<!-- English Revision: 579425:1205075 (outdated) -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<modulesynopsis metafile="mod_log_config.xml.meta">

<name>mod_log_config</name>
<description>サーバへのリクエストのロギング</description>
<status>Base</status>
<sourcefile>mod_log_config.c</sourcefile>
<identifier>log_config_module</identifier>

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

    <p>このモジュールは三つのディレクティブ提供します:
    ログファイルを作成するための <directive module="mod_log_config"
    >TransferLog</directive>,
    新しい書式を 定義する <directive module="mod_log_config">LogFormat</directive>,
    ログファイルと 書式を一度に定義する <directive module="mod_log_config"
    >CustomLog</directive> です。
    各リクエストが複数回ログ収集されるようにするために
    <directive>TransferLog</directive> ディレクティブと
    <directive>CustomLog</directive>
    ディレクティブは複数回使用することができます。</p>
</summary>
<seealso><a href="../logs.html">Apache ログファイル</a></seealso>

<section id="formats"><title>カスタムログ書式</title>

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

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

    <table border="1" style="zebra">
    <columnspec><column width=".2"/><column width=".8"/></columnspec>
    <tr><th>フォーマット文字列</th>
        <th>説明</th></tr>

    <tr><td><code>%%</code></td>
        <td>パーセント記号</td></tr>

    <tr><td><code>%a</code></td>
        <td>リモート IP アドレス</td></tr>

    <tr><td><code>%A</code></td>
        <td>ローカル IP アドレス</td></tr>

    <tr><td><code>%B</code></td>
        <td>レスポンスのバイト数。HTTP ヘッダは除く。</td></tr>

    <tr><td><code>%b</code></td>
        <td>レスポンスのバイト数。HTTP ヘッダは除く。CLF 書式。
        <em>すなわち</em>、1 バイトも送られなかったときは 0 ではなく、
        '<code>-</code>' になる</td></tr>

    <tr><td><code>%{<var>Foobar</var>}C</code></td>
        <td>サーバに送られたリクエスト中のクッキー <var>Foobar</var> の値</td></tr>

    <tr><td><code>%D</code></td>
        <td>リクエストを処理するのにかかった時間、マイクロ秒単位</td></tr>

    <tr><td><code>%{<var>FOOBAR</var>}e</code></td>
        <td>環境変数 <var>FOOBAR</var> の内容</td></tr>

    <tr><td><code>%f</code></td>
        <td>ファイル名</td></tr>

    <tr><td><code>%h</code></td>
        <td>リモートホスト</td></tr>

    <tr><td><code>%H</code></td>
        <td>リクエストプロトコル</td></tr>

    <tr><td><code>%{<var>Foobar</var>}i</code></td>
        <td>サーバに送られたリクエストの <code><var>Foobar</var>:</code>
        ヘッダの内容</td></tr>

    <tr><td><code>%l</code></td>
        <td>(identd からもし提供されていれば) リモートログ名。
        これは <module>mod_ident</module> がサーバに存在して、
        <directive module="mod_ident">IdentityCheck</directive>
        ディレクティブが <code>On</code> に設定されていない限り、
        <code>-</code> になります。</td></tr>

    <tr><td><code>%m</code></td>
        <td>リクエストメソッド</td></tr>

    <tr><td><code>%{<var>Foobar</var>}n</code></td>
        <td>他のモジュールからのメモ <var>Foobar</var> の内容</td></tr>

    <tr><td><code>%{<var>Foobar</var>}o</code></td>
        <td>応答の <code><var>Foobar</var>:</code> ヘッダの内容</td></tr>

    <tr><td><code>%p</code></td>
        <td>リクエストを扱っているサーバの正式なポート</td></tr>

    <tr><td><code>%{<var>format</var>}p</code></td>
        <td>サーバがリクエストを処理しているポートの公式
        <transnote>canonical</transnote> のポート番号か、
        サーバの実際のポート番号か、クライアント側の実際のポート番号かです。
        format に使える文字列は <code>canonical</code>, <code>local</code>,
        <code>remote</code> になります。
        </td></tr>

    <tr><td><code>%P</code></td>
        <td>リクエストを扱った子プロセスのプロセス ID</td></tr>

    <tr><td><code>%{<var>format</var>}P</code></td>
        <td>リクエストを扱ったワーカーのプロセス ID かスレッド ID。
        <var>format</var> として有効な値は <code>pid</code>, <code>tid</code>,
        <code>hextid</code> です。<code>hextid</code> を使うには
        APR 1.2.0 以降が必要です。
        </td></tr>

    <tr><td><code>%q</code></td>
        <td>問い合せ文字列 (存在する場合は前に <code>?</code> が追加される。
        そうでない場合は空文字列)</td></tr>

    <tr><td><code>%r</code></td>
        <td>リクエストの最初の行</td></tr>

    <tr><td><code>%s</code></td>
        <td>ステータス。内部でリダイレクトされたリクエストは、元々の
         リクエストのステータス --- 最後のステータスは <code>%&gt;s</code>
    </td></tr>

    <tr><td><code>%t</code></td>
        <td>リクエストを受付けた時刻。
        CLF の時刻の書式 (標準の英語の書式)</td></tr>

    <tr><td><code>%{<var>format</var>}t</code></td>
        <td><var>format</var> で与えられた書式による時刻。format は
         <code>strftime (3)</code> の
         書式である必要がある。(地域化されている可能性がある)</td></tr>

    <tr><td><code>%T</code></td>
        <td>リクエストを扱うのにかかった時間、秒単位</td></tr>

    <tr><td><code>%u</code></td>
        <td>リモートユーザ (認証によるもの。ステータス (<code>%s</code>) が
        401 のときは意味がないものである可能性がある)
    </td></tr>

    <tr><td><code>%U</code></td>
        <td>リクエストされた URL パス。クエリ文字列は含まない</td></tr>

    <tr><td><code>%v</code></td>
        <td>リクエストを扱っているサーバの正式な <directive
        module="core">ServerName</directive></td></tr>

    <tr><td><code>%V</code></td>
        <td><directive module="core"
        >UseCanonicalName</directive> の設定によるサーバ名</td></tr>

    <tr><td><code>%X</code></td>
        <td>応答が完了したときの接続ステータス:

        <table>
        <columnspec><column width=".2"/><column width=".6"/></columnspec>
        <tr><td><code>X</code> =</td>
            <td>応答が完了する前に接続が異常終了</td></tr>
        <tr><td><code>+</code> =</td>
            <td>応答が送られた後に接続を持続することが可能</td></tr>
        <tr><td><code>-</code> = </td>
            <td>応答が送られた後に接続が切られる</td></tr>
        </table>

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

    <tr><td><code>%I</code></td>
        <td>リクエストとヘッダを含む、受け取ったバイト数。
        0 にはならない。
        これを使用するためには <module>mod_logio</module> が必要</td></tr>

    <tr><td><code>%O</code></td>
        <td>ヘッダを含む、送信したバイト数。0 にはならない。
        これを使用するためには <module>mod_logio</module> が必要</td></tr>
    </table>

    <section id="modifiers"><title>修飾子</title>

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

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

    </section>

    <section id="format-notes"><title>その他注意点</title>

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

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

    </section>

    <section id="examples"><title>例</title>

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

      <dl>
        <dt>Common Log Format (CLF)</dt>
        <dd><code>"%h %l %u %t \"%r\" %&gt;s %b"</code></dd>

        <dt>バーチャルホスト付き Common Log Format</dt>
        <dd><code>"%v %h %l %u %t \"%r\" %&gt;s %b"</code></dd>

        <dt>NCSA extended/combined ログ書式</dt>
        <dd><code>"%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\"
        \"%{User-agent}i\""</code></dd>

        <dt>Referer ログ書式</dt>
        <dd><code>"%{Referer}i -&gt; %U"</code></dd>

        <dt>Agent (ブラウザ) ログ書式</dt>
        <dd><code>"%{User-agent}i"</code></dd>
      </dl>
    </section>
</section>

<section id="security"><title>セキュリティに関して</title>
    <p>ログファイルが保存されているディレクトリがサーバを起動した以外のユーザで
    書き込み可能なときにセキュリティの問題が発生する理由の詳細は<a
    href="../misc/security_tips.html#serverroot">セキュリティのこつ</a>
    を参照してください。</p>
</section>

<directivesynopsis>
<name>BufferedLogs</name>
<description>ディスクに書き出す前にメモリにログエントリをバッファする</description>
<syntax>BufferedLogs On|Off</syntax>
<default>BufferedLogs Off</default>
<contextlist><context>server config</context></contextlist>
<status>Experimental</status>
<compatibility>2.0.41 以降</compatibility>

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

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

<directivesynopsis>
<name>CustomLog</name>
<description>ログファイルの名前と書式を設定する</description>
<syntax>CustomLog  <var>file</var>|<var>pipe</var>
<var>format</var>|<var>nickname</var>
[env=[!]<var>environment-variable</var>]</syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

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

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

    <dl>
      <dt><var>file</var></dt>
      <dd><directive module="core">ServerRoot</directive>
      からの相対パスで表されるファイル名。</dd>

      <dt><var>pipe</var></dt>
      <dd>パイプ文字 "<code>|</code>" と、その後に標準入力からログの
      情報を受けとるプログラムへのパスが続いたもの。

      <note type="warning"><title>セキュリティ</title>
      <p>もしプログラムが使用された場合、
      <program>httpd</program> が起動されたユーザとして実行されます。これはサーバが
      root によって起動された場合は root になります。プログラムが
      安全であるように留意してください。</p>
      </note>
      <note type="warning"><title>注</title>
        <p>Unix でないプラットフォームでファイルのパスを入力しているときは、
        使用しているプラットフォームがバックスラッシュの使用を許可していた
        として、通常のスラッシュだけを使うように気をつけてください。
        一般的に、設定ファイル中では常に普通のスラッシュのみを使うようにする
        方が良いです。</p>
      </note></dd>
    </dl>

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

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

    <example>
      # CustomLog with format nickname<br />
      LogFormat "%h %l %u %t \"%r\" %&gt;s %b" common<br />
      CustomLog logs/access_log common<br />
      <br />
      # CustomLog with explicit format string<br />
      CustomLog logs/access_log "%h %l %u %t \"%r\" %&gt;s %b"
    </example>

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

    <p>環境変数は <module>mod_setenvif</module> モジュールと
    <module>mod_rewrite</module> モジュールの両方もしくは
    片方を用いてリクエストごとに設定することができます。
    例えば、サーバにあるすべての GIF 画像へのリクエストを別のログファイル
    には記録したいけれど、メインログには記録したくない、というときは
    以下のものを使うことができます:</p>
    
    <example>
      SetEnvIf Request_URI \.gif$ gif-image<br />
      CustomLog gif-requests.log common env=gif-image<br />
      CustomLog nongif-requests.log common env=!gif-image
    </example>

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

    <example>
    SetEnvIf Referer example\.com localreferer<br />
    CustomLog referer.log referer env=!localreferer
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>LogFormat</name>
<description>ログファイルで使用する書式を設定する</description>
<syntax>LogFormat <var>format</var>|<var>nickname</var>
[<var>nickname</var>]</syntax>
<default>LogFormat "%h %l %u %t \"%r\" %>s %b"</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

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

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

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

    <example><title>例</title>
      LogFormat "%v %h %l %u %t \"%r\" %&gt;s %b" vhost_common
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>TransferLog</name>
<description>ログファイルの位置を指定</description>
<syntax>TransferLog <var>file</var>|<var>pipe</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

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

    <example><title>例</title>
      LogFormat "%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\" \"%{User-agent}i\""<br />
      TransferLog logs/access_log
    </example>
</usage>
</directivesynopsis>

</modulesynopsis>