<title>Log Configuration</title>

<summarylist/>

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

<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 following example configures System.out for a host.  All web-apps in the
host will write to the same output file.

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

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

</subsection>

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

<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>

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

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

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

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

</subsection>

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

<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.

<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.<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>

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.

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

</subsection>

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

<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.

<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.<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>

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.

<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>

</subsection>

<subsection title="log">
<sum>Starts logging for debugging.</sum>

<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>

For example, to log everything to standard error use:

<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:

<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/>Logging uses the com.caucho.vfs.LogStream interface.  A typical use is
as follows

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

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

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

</subsection>

<section title="Log Paths">

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

<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>

</section>