config-log.xtp

RESIN 3.2 最新源码

</tr>
<tr>
  <td>path</td>
  <td>Output path for the stream, see <a href="#path">"Log Paths"</a>.</td>
  <td>required</td>
</tr>
<tr>
  <td>path-format</td>
  <td>Selects a format for generating path names.  The syntax is the same as for archive-format</td>
  <td>optional</td>
</tr>
<tr>
  <td>rollover-count</td>
  <td>maximum number of rollover files before the oldest ones get overwritten.
      See <a href="#rollover">Rollovers</a>. 
    </td>
 <td>none</td>
</tr>
<tr>
  <td>rollover-period</td>
  <td>how often to rollover the log.  Specify in days (15D), weeks (2W), 
        months (1M), or hours (1h). See <a href="#rollover">Rollovers</a>. 
    </td>
 <td>none</td>
</tr>
<tr>
  <td>rollover-size</td>
  <td>maximum size of the file before a rollover occurs, in bytes (50000), 
        kb (128kb), or megabytes (10mb).  
        See <a href="#rollover">Rollovers</a>.
    </td>
  <td>1mb
  </td>
</tr>
<tr>
  <td>timestamp</td>
  <td>a timestamp <a href="#timestamp">format string</a> to use at the beginning of each log line.</td>
  <td>no timestamp</td>
</tr>
</deftable-childtags>

<p>The default archive format is</p>
<pre>
  <var>path</var> + ".%Y%m%d" or
  <var>path</var> + ".%Y%m%d.%H" if rollover-period &lt; 1 day.
</pre>

<p>The following example configures <var>System.out</var> for a 
<a config-tag="host"/>.  Unless a <a config-tag="web-app">web-app</a> overrides
with it's own <code>stdout-log</code>, all web-apps in the host will write to
the same output file.</p>

<example>
...
&lt;host id='foo.com'&gt;
  &lt;stdout-log path='/var/log/foo/stdout.log'
              rollover-period='1W'/&gt;
  ...
&lt;/host&gt;
...
  </example>

</s2>

<s2 title="stderr-log" type="defun">
<parents>resin, server, host-default, web-app-default, web-app</parents>
<default>use the JDK's destination for System.err</default>

<p>Configure the destination for <var>System.err</var>.</p>

<p>Usage of the <var>stderr-log</var> overrides a previous usage.  For
example, specifying <var>stderr-log</var> as a child of a 
<a config-tag="web-app"/> causes a redirection of <var>System.err</var> for
that web application only, and will override the <var>System.err</var>
location in the enclosing <a config-tag="host"/>.</p>

<warn>The <var>path</var> must not be the same as the path specified on the
command line with <code>-stderr</code>.  If it is, there will be conflicts with
which process owns the file.</warn>

<deftable-childtags>
<tr><td>path
    </td><td>Output path for the stream, see <a href="#path">"Log Paths"</a>.  
    </td><td>required
</td></tr>
<tr>
  <td>path-format</td>
  <td>Selects a format for generating path names.  The syntax is the same as for archive-format</td>
  <td>optional</td>
</tr>
<tr><td>timestamp
    </td><td>a timestamp <a href="#timestamp">format string</a> 
        to use at the beginning of each log line.
    </td><td>no timestamp
    </td></tr><tr><td>rollover-count
    </td><td>maximum number of rollover files before the oldest ones get overwritten.
        See <a href="#rollover">Rollovers</a>. 
    </td><td>none
</td></tr><tr><td>rollover-period
    </td><td>how often to rollover the log.  Specify in days (15D), weeks (2W), 
        months (1M), or hours (1h). See <a href="#rollover">Rollovers</a>. 
    </td><td>none
</td></tr><tr><td>rollover-size
    </td><td>maximum size of the file before a rollover occurs, in bytes (50000), 
        kb (128kb), or megabytes (10mb).  
        See <a href="#rollover">Rollovers</a>.
    </td><td>1mb
</td></tr><tr><td>archive-format
    </td><td>the format for the archive filename when a rollover occurs,
        see <a href="#rollover">Rollovers</a>.
    </td><td>see below
</td></tr></deftable-childtags>

<p>The default archive format is
</p><pre>
  <var>path</var> + ".%Y%m%d" or
  <var>path</var> + ".%Y%m%d.%H" if rollover-period &lt; 1 day.
</pre>

<p>The following example configures <var>System.err</var> for a 
<a config-tag="host"/>.  Unless a <a config-tag="web-app">web-app</a> overrides
with it's own <code>stderr-log</code>, all web-apps in the host will write to
the same output file.</p>

<example>
...
&lt;host id='foo.com'&gt;
  &lt;stderr-log path='/var/log/foo/stderr.log'
              rollover-period='1W'/&gt;
  ...
&lt;/host&gt;
...
</example>

</s2>

</s1>

<s1 title="Access logging">
<parents>server, host-default, host, web-app-default, web-app</parents>

<p>Specify the access log file.</p>

<p>As a child of <a config-tag="web-app"/>, overrides the
definition in the <a config-tag="host"/> that the web-app is
deployed in. As a child of <a config-tag="host"/>, overrides the
definition in the <a config-tag="server"/> that the host is
in.</p>

<deftable-childtags>
<tr>
  <td>path</td>
  <td>Output path for the log entries, see 
        <a href="#path">"Log Paths"</a>.
  </td>
  <td>required</td>
</tr>
<tr>
  <td>path-format</td>
  <td>Selects a format for generating path names.  The syntax is the same as for archive-format</td>
  <td>optional</td>
</tr>
<tr><td>format
    </td><td>Access log format.
    </td><td>see below
</td></tr><tr><td>rollover-count
    </td><td>maximum number of rollover files before the oldest ones get overwritten.
        See <a href="#rollover">Rollovers</a>. 
    </td><td>none
</td></tr><tr><td>rollover-period
    </td><td>how often to rollover the log.  Specify in days (15D), weeks (2W), 
        months (1M), or hours (1h). See <a href="#rollover">Rollovers</a>. 
    </td><td>none
</td></tr><tr><td>rollover-size
    </td><td>maximum size of the file before a rollover occurs, in bytes (50000), 
        kb (128kb), or megabytes (10mb).  
        See <a href="#rollover">Rollovers</a>.
    </td><td>1mb
</td></tr><tr><td>archive-format
    </td><td>the format for the archive filename when a rollover occurs,
        see <a href="#rollover">Rollovers</a>.
    </td><td>see below
</td></tr><tr><td>auto-flush
    </td><td>true to flush the memory buffer with each request
    </td><td>false
</td></tr><tr><td>resin:type
    </td><td>a class extending <a href="javadoc|com.caucho.server.log.AccessLog|"/>
        for custom logging
    </td><td>com.caucho.server.log.AccessLog
</td></tr><tr><td>init</td><td>bean-style initialization for the custom class</td><td>n/a
</td></tr></deftable-childtags>

<p>The default archive format is
</p><pre>
  <var>path</var> + ".%Y%m%d" or
  <var>path</var> + ".%Y%m%d.%H" if rollover-period &lt; 1 day.
</pre>

<example>
...
&lt;host id=''&gt;
  &lt;access-log path='log/access.log'&gt;
    &lt;rollover-period&gt;2W&lt;/rollover-period&gt;
  &lt;/access-log&gt;
  ...
&lt;/host&gt;
...
</example>

<p>The access log formatting variables follow the Apache variables:</p>
<!-- duplicated in config-log.xtp, cluster.xtp, host-tags.xtp -->
<deftable>
<tr><td>%b</td>
    <td>result content length</td></tr>
<tr><td>%D</td>
    <td>time taken to complete the request in microseconds (since 3.0.16)</td></tr>
<tr><td>%h</td>
    <td>remote IP addr</td></tr>
<tr><td>%{<var>xxx</var>}i</td>
    <td>request header <var>xxx</var></td></tr>
<tr><td>%{<var>xxx</var>}o</td>
    <td>response header <var>xxx</var></td></tr>
<tr><td>%{<var>xxx</var>}c</td>
    <td>cookie value <var>xxx</var></td></tr>
<tr><td>%n</td>
    <td>request attribute</td></tr>
<tr><td>%r</td>
    <td>request URL</td></tr>
<tr><td>%s</td>
    <td>status code</td></tr>
<tr><td>%{<var>xxx</var>}t</td>
    <td>request date with optional time format string.</td></tr>
<tr><td>%T</td>
    <td>time taken to complete the request in seconds</td></tr>
<tr><td>%u</td>
    <td>remote user</td></tr>
<tr><td>%U</td>
    <td>request URI</td></tr>
</deftable>

<p>The default format is:</p>

<def>
"%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\" \"%{User-Agent}i\""
</def>

<p><var>resin:type</var> allows for custom logging.  Applications can
extend a custom class from <a href="javadoc|com.caucho.http.log.AccessLog|"/>.  
<a href="ioc-bean.xtp">Bean-style initialization</a> can be used to set bean
parameters in the custom class.</p>

<example>
...
&lt;host id='foo.com'&gt;
  &lt;access-log resin:type='test.MyLog'&gt;
             path='$server-root/foo/error.log'
             rollover-period='1W'&gt;
    &lt;init&gt;
      &lt;foo&gt;bar&lt;/foo&gt;
    &lt;/init&gt;
  &lt;/access-log&gt;
  ...
&lt;/host&gt;
...
</example>

</s1> <!-- access logging -->

<s1 name="path" title="Log Paths">

<p><var>path</var> is used to configure a destination for the messages.  Typically,
<code>access-log</code>, <code>stdout-log</code>, and <code>stderr-log</code> are configured
to go to files, and <code>log</code> is configured to go to a file or to
<var>stderr</var> or <var>stdout</var> so that they show up on the console screen.
</p>

<deftable>
<tr><th>Path</th><th>Result
</th></tr><tr><td><var>filesystem path</var></td><td>output log entries to a file
</td></tr><tr><td>stdout:</td><td>output log entries to stdout
</td></tr><tr><td>stderr:</td><td>output log entries to stderr
</td></tr></deftable>

<example title="Log messages to stdout">
  &lt;log name="" level="all" path="stdout:"/&gt;
</example>

<p>You can use the <a href="config-el.xtp">Environment EL variables</a> as part
of your filesystem path:</p>

<example title="Filesystem path using Environment EL variables">
  &lt;log name="" level="all" 
       path="log/debug-${server.id}.log"
       rollover-period="1h" rollover-count="1"/&gt;
</example>

</s1>

<s1 name="rollover" title="Rollovers">
<p>Log rollovers are a way to stop your log files from getting too large.  When
a rollover is triggered, the existing log file is renamed and a new file is
started.</p>

<s2 title="Size based rollover">
<p>A size based rollover is triggered when the size of the file reaches a
certain amount.  The default Resin behaviour for log's is to rollover when the
file size reaches 1mb.</p>

<p><code>rollover-size</code> is used to specify the maximum size, and can be in
bytes (50000), kilobytes (128kb), or megabytes (10mb).  A value of <code>-1</code>
disables size based rollovers.</p>
</s2>

<s2 title="Time based rollover">

<p>A time based rollover is triggered when a certain period of time has passed
since the last rollover.  The default Resin behaviour is to perform no time
based rollover, unless rollover-size has been disabled with a value of -1 in
which case the default time period is 1 month.</p>

<p><code>rollover-period</code> is used to specify the time period, and can be in
days (15D), weeks (2W), months (1M), or hours (1h).</p>
</s2>

<s2 title="Archive files">
<p>When a rollover is triggered, the log file is renamed (archived) and a new
log file is started.</p>

<p><code>archive-format</code> is used to specify the name of the archive file.  It
can contain regular characters, <a href="el-var.xtp">EL Environment
variables</a>, and % codes that capture the current date and time.  The % codes
are the same as the ones used for <code>timestamp</code> 
(see <a href="#timestamp">Timestamp format string)</a>.</p>

<p>The default behaviour depends on the value of rollover-period.  If
rollover-period is greater than one day, or is not being used because
rollover-size has been specified, the archive filename is the original path
with <code>.%Y%m%d</code> appended.  If rollover-period is less than one day, the
archive filename is the original path with <code>.%Y%m%d.%H</code> appended.</p>

</s2>

<s2 title="Disabling rollovers">

<p>To completely disable rollovers, set the <code>rollover-size</code> to such a
high number that it will never occur:</p>

<example title="disable log rollovers">
  &lt;stdout-log path="log//stdout.log" rollover-size="1024mb"/&gt;
</example>

</s2>

<s2 title="Compression">

<p>Rollover log files can be compressed with gzip or zip.  The
extension of the archive-format determines the compression.</p>

<example>
&lt;log name="" level="warning" path='log/error.log'
     archive-format="%Y-%m-%d.error.log.gz"
     rollover-period="1D"/&gt;

&lt;access-log path="log/access.log"
            archive-format="access-%Y%m%d.log.gz"
            rollover-period="1D"/&gt;
</example>

</s2>

</s1> <!-- rollovers -->

<s1 name="timestamp" title="Timestamp format string">

<p>The <var>timestamp</var> for log tags is a format string which can contain
percent codes which are substituted with time and date values.</p>

<deftable>
<tr><th>Code</th><th>Meaning
</th></tr><tr><td>%a</td><td>day of week (short)
</td></tr><tr><td>%A</td><td>day of week (verbose)
</td></tr><tr><td>%b</td><td>day of month (short)
</td></tr><tr><td>%B</td><td>day of month (verbose)
</td></tr><tr><td>%c</td><td>Java locale date
</td></tr><tr><td>%d</td><td>day of month (two-digit)
</td></tr><tr><td>%H</td><td>24-hour (two-digit)
</td></tr><tr><td>%I</td><td>12-hour (two-digit)
</td></tr><tr><td>%j</td><td>day of year (three-digit)
</td></tr><tr><td>%m</td><td>month (two-digit)
</td></tr><tr><td>%M</td><td>minutes
</td></tr><tr><td>%p</td><td>am/pm
</td></tr><tr><td>%S</td><td>seconds
</td></tr><tr><td>%s</td><td>milliseconds
</td></tr><tr><td>%W</td><td>week in year (three-digit)
</td></tr><tr><td>%w</td><td>day of week (one-digit)
</td></tr><tr><td>%y</td><td>year (two-digit)
</td></tr><tr><td>%Y</td><td>year (four-digit)
</td></tr><tr><td>%Z</td><td>time zone (name)
</td></tr><tr><td>%z</td><td>time zone (+/-0800)
</td></tr></deftable>


<example title="Example: typical timestamp for the log tag">
&lt;resin xmlns="http://caucho.com/ns/resin">

  &lt;log-handler name='' path='stderr:' timestamp="[%H:%M:%S.%s]"/&gt;

  ...
&lt;/resin>
</example>

<results>
[22:50:11.648] WebApp[/doc] starting
[22:50:11.698] http listening to *:8080
[22:50:11.828] hmux listening to *:6800
</results>

</s1>

</body>
</document>