<s1 title="Log Configuration">

<summarylist/>

<defun title="stdout-log">
<p>Configures the destination for System.out.  Each &lt;host> and
&lt;web-app> can have its own individual System.out location.</p>

<deftable>
<tr><th>Attribute<th>Description<th>Default
<tr><td>id (or href)<td>Filesystem path for the stream<td>required
<tr><td>rollover-period<td>how often to rollover the log.  Normally in days (15D), weeks (2W) or months (1M).<td>none
<tr><td>rollover-size<td>max size of the log before a rollover in bytes.<td>1 meg
</deftable>

<p>The following example configures System.out for a host.  All web-apps in the
host will write to the same output file.</p>

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

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

</defun>

<defun title="stderr-log">
<p>Configures the destination for System.err.  Each &lt;host> and
&lt;web-app> can have its own individual System.err location.</p>

<deftable>
<tr><th>Attribute<th>Description<th>Default
<tr><td>id (or href)<td>Filesystem path for the stream<td>required
<tr><td>rollover-period<td>how often to rollover the log.  Normally in days (15D), weeks (2W) or months (1M).<td>none
<tr><td>rollover-size<td>max size of the log before a rollover.<td>1 meg
</deftable>

<p>The path <var/href/> may use path and regular expression variables.</p>

<p>The following example configures System.err for a host.
All web-apps in the host will write to the same output file.</p>

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

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

</defun>

<defun title="access-log">
<p>The access-log configures the logging of each request.</p>

<p>The access-log can be configured either in the &lt;http-server>, &lt;host>,
or &lt;web-app> context.  It will apply within the context.</p>

<deftable>
<tr><th>Attribute<th>Description<th>Default
<tr><td>id<td>The access log path.<td>required
<tr><td>format<td>Access log format.<td>see below
<tr><td>rollover-period<td>how often to rollover the log.
Normally in days (15D), weeks (2W) or months (1M).<td>none
<tr><td>rollover-size<td>max size of the log before a rollover in bytes.<td>10 meg
<tr><td>class-name<td>Class implementing AbstractAccessLog for custom logging.<td>none
<tr><td>init-param<td>Parameters for the custom log.<td>none
</deftable>

<p>The access log formatting variables follow the Apache variables:</p>

<deftable>
<tr><td>%b<td>result content length
<tr><td>%h<td>remote IP addr
<tr><td>%{<var/xxx/>}i<td>request header <var/xxx/>
<tr><td>%{<var/xxx/>}o<td>response header <var/xxx/>
<tr><td>%{<var/xxx/>}c<td>cookie value <var/xxx/>
<tr><td>%n<td>request attribute
<tr><td>%r<td>request URL
<tr><td>%s<td>status code
<tr><td>%{<var/xxx/>}t<td>request date with optional time format string.
<tr><td>%T<td>time of request in seconds
<tr><td>%u<td>remote user
<tr><td>%U<td>request URI
</deftable>

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

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

<example>
&lt;host id=''>

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

 ...

&lt;/host&gt;
</example>

<p>The class-name attribute allows for custom logging.  Application can
extend a custom class from com.caucho.http.log.AbstractAccessLog.  The
init-param parameters set bean parameters in the custom class.</p>

<example>
...
&lt;host id='foo.com'>
  &lt;access-log href='$server-root/foo/error.log'
             rollover-period='1W'
             class-name='test.MyLog'>
    &lt;init-param foo='bar'/>
  &lt;/access-log>
  ...
&lt;/host>
...
</example>

</defun>

<defun title="error-log">
<p>The error-log configures the destination for ServletContext.log()
messages.  The error-log is also used for exceptions not caught
by the application.</p>

<p>The error-log can be configured either in the &lt;http-server>, &lt;host>,
or &lt;web-app> context.  It will apply within the context.</p>

<deftable>
<tr><th>Attribute<th>Description<th>Default
<tr><td>id<td>The access log path.<td>required
<tr><td>rollover-period<td>how often to rollover the log.
Normally in days (15D), weeks (2W) or months (1M).<td>none
<tr><td>rollover-size<td>max size of the log before a rollover in bytes.<td>1 meg
<tr><td>class-name<td>Class implementing AbstractAccessLog for custom logging.<td>none
<tr><td>init-param<td>Parameters for the custom log.<td>none
</deftable>

<p>The class-name attribute allows for custom logging.  Application can
extend a custom class from com.caucho.http.log.AbstractErrorLog.  The
init-param parameters set bean parameters in the custom class.</p>

<example>
...
&lt;host id='foo.com'>
  &lt;error-log href='$server-root/foo/error.log'
             rollover-period='1W'
             class-name='test.MyErrorLog'>
    &lt;init-param foo='bar'/>
  &lt;/error-log>
  ...
&lt;/host>
...
</example>

</defun>

<defun title="log">
<p>Starts logging for debugging.</p>

<deftable>
<tr><th>Attribute<th>Meaning<th>default
<tr><td>id<td>Name of debugging section<th>none
<tr><td>href<td>Destination file<td>none
<tr><td>timestamp<td>timestamp format<td>none
<tr><td>rollover-count<td>how many rotated (<var/href.n/>) logs to keep.<td>2
<tr><td>rollover-period<td>How often to rotate the log.<td>none
</deftable>

<p>For example, to log everything to standard error use:</p>

<example>
&lt;caucho.com&gt;
  &lt;log id='/' href='stderr:' timestamp="[%H:%M:%S.%s]"/>
  ...
&lt;/caucho.com&gt;
</example>

<deftable>
<tr><th>log <var/id/> value<th>Meaning
<tr><td>/<td>Debug everything
<tr><td>/caucho.com/jsp<td>Debug jsp
<tr><td>/caucho.com/java<td>Java compilation
<tr><td>/caucho.com/xsl<td>XSL debugging
<tr><td>/caucho.com/tcp-server
    <td>TCP connections
<tr><td>/caucho.com/thread
    <td>Thread creation and deletion
<tr><td>/caucho.com/sql
    <td>Database pooling
<tr><td>/caucho.com/http
    <td>HTTP related information
<tr><td>/caucho.com/http/session
    <td>HTTP sessions
</deftable>

<p>The timestamp can include the following patterns:</p>

<deftable>
<tr><th>Pattern<th>Meaning
<tr><td>%a<td>short weekday (mon, tue, ...)
<tr><td>%A<td>long weekday (Monday, Tuesday, ...)
<tr><td>%b<td>short month (Jan, Feb, ...)
<tr><td>%B<td>long month (January, February, ...)
<tr><td>%c<td>locale specific date
<tr><td>%d<td>day of month
<tr><td>%H<td>24-hour
<tr><td>%I<td>12-hour
<tr><td>%j<td>day of year
<tr><td>%m<td>month
<tr><td>%M<td>minute
<tr><td>%p<td>am/pm
<tr><td>%S<td>seconds
<tr><td>%s<td>milliseconds
<tr><td>%W<td>week of year
<tr><td>%w<td>day of week
<tr><td>%y<td>2-digit year
<tr><td>%Y<td>4-digit year
</deftable>

<p>Debugging uses the com.caucho.vfs.LogStream interface.  A typical use is
as follows</p>

<example>
import com.caucho.vfs.*;

public class Foo {
  static WriteStream dbg = LogStream.open("/caucho.com/foo");

  ...
  void doFoo()
  {
    if (dbg.canWrite())
      dbg.log("executing foo");
  }
  ...
}
</example>

</defun>

<s2 title="Log Paths">

<p>The path <var/href/> may use path and regular expression variables.</p>

<deftable>
<tr><th>Variable<th>Value
<tr><td>$server-root<td>The root of the server instance.  Same as the -server-root argument.
<tr><td>$host-root<td>The app-dir of the enclosing &lt;host>
<tr><td>$app-dir<td>The app-dir of the enclosing &lt;web-app>
<tr><td>$host0 ... $host9<td>Regular expression replacement from a host url-regexp.
<tr><td>$app0 ... $app9<td>Regular expression replacement from a web-app url-regexp.
<tr><td>$0 ... $9<td>Regular expression replacement for the containing context (host or web-app)
<tr><td>$<var/foo/><td>Java property value from System.getProperty("foo")
</deftable>

</s2>
</s1>