config-log.xtp

RESIN 3.2 最新源码

  <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>mbean-name</td>
  <td>an mbean name, see <a href="#mbean">MBean control</a>.</td>
  <td>no mbean name, no mbean registration</td>
</tr>
<tr>
  <td>handler</td>
  <td>add a custom Handler, the name of a class that extends 
        <a href="javadoc|java.util.logging.Handler"/>
    </td>
  <td>&#160;</td>
</tr>
<tr>
  <td>formatter</td>
  <td>set a custom Formatter, the name of a class that extends 
        <a href="javadoc|java.util.logging.Formatter"/>
    </td>
  <td>none, or <a href="javadoc|com.caucho.log.ELFormatter"/> if 
        <var>format</var> is used.</td>
</tr>
</deftable-childtags>

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

<def title="default archive-format">
<var>path</var> + ".%Y%m%d"    if rollover-period >= 1 day.
<var>path</var> + ".%Y%m%d.%H" if rollover-period &lt; 1 day.
</def>

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

<example title="Example: logging everything to System.err">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"/&gt;
  ...
&lt;/resin&gt;
</example>

<p>A useful technique is to enable full debug logging to track down a problem:
</p>

<example title="debug logging">

&lt;resin&gt;
  ...
  &lt;log name='' level='finer' path='log/debug.log'
       timestamp="[%H:%M:%S.%s]"
       rollover-period='1h' rollover-count='1'/&gt;
  ...
&lt;/resin&gt;
</example>

<p>More examples of debug logging are in the <a href="troubleshoot-technique.xtp#debug-log">Troubleshooting</a> section.</p>

<p>The class that corresponds to &lt;log&gt; is <a href="javadoc|com.caucho.log.LogConfig|"/>.</p>

<s3 name="Format-String" title="Log format string">

<p>The <var>format</var> for log tags is used to specify a format string for each
log message.  <code>format</code> recognizes EL-expressions. The EL variable
<var>log</var> is a 
<a href="javadoc|com.caucho.log.ELFormatter.ELFormatterLogRecord|"/>
 object.</p>

<example title="log format string">

&lt;log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
     format=" ${log.level} ${log.loggerName} ${log.message}"/&gt;

</example>

<deftable title="log EL variable 'log' is a LogRecord">
<tr><th>Accessor</th><th>Value
</th></tr><tr><td>${log.level}</td><td>The level of the log record
</td></tr><tr><td>${log.name}</td><td>The source loggers name
</td></tr><tr><td>${log.shortName}</td><td>A shorter version of the source loggers name, "Foo" instead of "com.hogwarts.Foo"
</td></tr><tr><td>${log.message}</td><td>The message, with no formatting or localization
</td></tr><tr><td>${log.millis}</td><td>event time in milliseconds since 1970
</td></tr><tr><td>${log.sourceClassName}</td><td>Get the name of the class that issued the logging request (may not be available at runtime)
</td></tr><tr><td>${log.sourceMethodName}</td><td>Get the name of the method that issued the logging request (may not be available at runtime)
</td></tr><tr><td>${log.threadID}</td><td>Get an <var>int</var> identifier of the thread where the logging request originated
</td></tr><tr><td>${log.thrown}</td><td>Get any <a href="javadoc|java.lang.Throwable|"/> associated with the logging request
</td></tr></deftable>

<p>You can also use the <a href="el-var.xtp">Environment EL variables</a> in your format string:</p>

<example title="log format string using an Environment EL variable.">
&lt;host ...&gt;

  &lt;web-app&gt;
    &lt;log name='' level='all' path='log/debug.log' timestamp="[%H:%M:%S.%s]"
         format=" [<b>${app.contextPath}</b>] ${log.message}"/&gt;

    ...
  &lt;/web-app&gt;

  ...

&lt;/host&gt;
</example>
<results>
[14:55:10.189] [/foo] `null' returning JNDI java:
       model for EnvironmentClassLoader[web-app:http://localhost:8080/foo]
[14:55:10.189] [/foo] JNDI lookup `java:comp/env/caucho/auth'
       exception javax.naming.NameNotFoundException: java:comp/env/caucho/auth
[14:55:10.199] [/foo] Application[http://localhost:8080/foo] starting

</results>

<p>The <a href="el-var.xtp#sprintf">fmt.sprintf()</a> function can
space pad the values and make the results look a little nicer:</p>

<example title="fmt.sprintf() in log format string">
&lt;log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
     format=" ${fmt.sprintf('%-7s %45s %s',log.level,log.loggerName,log.message)}"/&gt;
</example>

<results>
[14:28:08.137] INFO com.caucho.vfs.QJniServerSocket Loaded Socket JNI library.
[14:28:08.137] INFO com.caucho.server.port.Port http listening to *:8080
[14:28:08.137] INFO com.caucho.server.resin.ServletServer ServletServer[] starting
[14:28:08.307] INFO com.caucho.server.port.Port hmux listening to localhost:6802
[14:28:08.437] INFO com.caucho.server.host.Host Host[] starting 
</results>


<p><a href="config-el.xtp#sprintf">fmt.sprintf()</a> and <a href="config-el.xtp#timestamp">fmt.timestamp()</a> can be used to produce CSV files:</p>

<example title="CSV log files">
&lt;log name='' level='all' path='log/debug.csv' timestamp=""
     format="${fmt.sprintf('%vs,%d,%d,%vs,%vs',fmt.timestamp('%Y-%m-%d %H:%M:%S.%s'), 
               log.threadID, log.level.intLevel(), log.loggerName, log.message)}"/&gt;
</example>

<results>
"2003-11-17 14:46:14.529",10,800,"com.caucho.vfs.QJniServerSocket",
            "Loaded Socket JNI library."
"2003-11-17 14:46:14.549",10,800,"com.caucho.server.port.Port",
            "http listening to *:8080"
"2003-11-17 14:46:14.549",10,800,"com.caucho.server.resin.ServletServer",
            "ServletServer[] starting"
"2003-11-17 14:46:14.719",10,800,"com.caucho.server.port.Port",
            "hmux listening to localhost:6802"
"2003-11-17 14:46:14.850",10,800,"com.caucho.server.host.Host",
            "Host[] starting"
"2003-11-17 14:46:15.100",10,800,"com.caucho.server.webapp.Application",
            "Application[http://localhost:8080/freelistbm] starting"
</results>

</s3> <!-- Format-String -->

</s2>

<s2 title="Log Handlers">

<p>Resin provides a number of predefined custom log handlers for common
logging patterns, including sending messages to JMS, <a href="hmtp">HMTP</a>,
and the syslog service.  Creating your own custom handler is also
straightforward.</p>

<s3 name="bam" title="BamHandler, uri='bam:' (3.2.0)">

<p>The BAM handler publishes the log message to a <a href="hmtp.xtp">BAM</a>
agent.  The agent can be a custom HMTP service to process log messages.
The <code>BamHandler</code> needs a JID (Jabber id) as the address of the
target service.</p>

<example title="Example: BAM handler configuration">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;log-handler name="com.foo" level="warning" uri="bam:">
    &lt;init>
       &lt;to>test@localhost&lt;/to>
   &lt;/init>
  &lt;/log-handler>

&lt;/web-app>
</example>

</s3>

<s3 name="event" title="EventHandler, uri='event:'">

<p>The event handler publishes a <code>LogEvent</code> to the WebBeans event
system.  Any WebBeans component with an <code>@Observes</code> method for
<code>LogEvent</code> will receive the notifications.  The log handler
classname is <code>com.caucho.log.handler.EventHandler</code> and the
shortcut is uri="event:".</p>

<example title="Example: event handler configuration">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;log-handler name="com.foo" level="warning" uri="event:"/>

&lt;/web-app>
</example>

</s3>

<s3 name="jms" title="JmsHandler, uri='jms:'">

<p>The JMS handler publishes the log message to a
<a href="resin-messaging.xtp">JMS</a> queue.</p>

<example title="Example: JMS handler configuration">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;jms-queue name="myQueue" uri="memory:"/>

  &lt;log-handler name="com.foo" level="warning" uri="jms:">
    &lt;init>
       &lt;target>${myQueue}&lt;/target>
   &lt;/init>
  &lt;/log-handler>

&lt;/web-app>
</example>

</s3>

<s3 name="mail" title="MailHandler, uri='mail:' (3.2.0)">

<p>The Mail handler sends log messages to an email address.  To keep the
number of mails down, the handler will concatenate messages and only send
them after a period of time.
</p>

<deftable title="mail: attributes">
<tr>
  <th>attribute</th>
  <th>description</th>
  <th>default</th>
</tr>
<tr>
  <td>to</td>
  <td>mail address</td>
  <td>required</td>
</tr>
<tr>
  <td>delay-time</td>
  <td>time to wait before sending first mail</td>
  <td>1m</td>
</tr>
<tr>
  <td>mail-interval-min</td>
  <td>minimum time between mail messages</td>
  <td>1h</td>
</tr>
<tr>
  <td>properties</td>
  <td>javamail properties in property file format</td>
  <td></td>
</tr>
</deftable>

<example title="Example: Mail handler configuration">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;log-handler name="" level="warning" uri="mail:">
    &lt;init>
       &lt;to>[e-mail]&lt;/to>
       &lt;properties>
         mail.smtp.host=127.0.0.1
         mail.smtp.port=25
       &lt;/properties>
   &lt;/init>
  &lt;/log-handler>

&lt;/web-app>
</example>

</s3>

<s3 name="syslog" title="SyslogHandler, uri='syslog:'">

<p>On Unix systems, the SyslogHandler lets you log messages to syslog.</p>

<example title="Example: syslog configuration">
&lt;resin xmlns="http://caucho.com/ns/resin">

&lt;log-handler name="" level="warning" uri="syslog:"&gt;
    &lt;init>
      &lt;facility&gt;daemon&lt;/facility&gt;
      &lt;severity&gt;notice&lt;/severity&gt;
    &lt;/init>
&lt;/log-handler&gt;
</example>

<p>The possible values for <var>facility</var> are user, mail, daemon, auth, lpr,
news, uucp, cron, authpriv, ftp, local0, local1, local2, local3, local4,
local5, local6, local7. The default is <i>daemon</i>.</p>

<p>The possible values for <var>severity</var> are emerg, alert, crit, err,
warning, notice, info, debug. The default is <i>info</i>.</p>

<p>See also `<code>man 3 syslog</code>' and `<code>man syslog.conf</code>'.
</p></s3>

<s3 title="custom handler">

<example title="Example: custom formatter configuration">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;log-handler name="" level="warning" class="demo.MyHandler"/&gt;
  
&lt;/web-app>
</example>

<example title="Example: MyHandler.java">
package demo;

import java.util.logging.*;

public class MyHandler extends Handler
{
  @Override
  public void publish(LogRecord record)
  {
    System.out.println(getFormatter().format(record));
  }
  
  @Override
  public void flush();
  {
  }
  
  @Override
  public void close();
  {
  }
}
</example>

</s3>

</s2> <!-- handler -->

<s2 title="Log Formatting">

<p>Sites may wish to change the formatting of log messages to gather information
more appropriate for the site.  The formatter can be custom-configured just like
the handlers.</p>

<s3 title="custom handler">

<example title="Example: custom formatter configuration">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;log-handler name="com.foo" level="warning" path="WEB-INF/log.log"&gt;
    &lt;formatter class="qa.MyFormatter"/>
  &lt;/log-handler>
  
&lt;/web-app>
</example>

<example title="Example: MyFormatter.java">
package demo;

import java.util.logging.*;

public class MyFormatter extends Formatter
{
  @Override
  public String format(LogRecord record)
  {
    return "[" + record.getLevel() + "] " + record.getMessage();
  }
}
</example>

</s3>

</s2> <!-- formatter -->

</s1> <!-- java.util.logging  -->

<s1 title="Standard Output Redirection">

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

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

<p>Usage of the <var>stdout-log</var> overrides a previous usage.  For
example, specifying <var>stdout-log</var> as a child of a 
<a config-tag="web-app"/> causes a redirection of <var>System.out</var> for
that web application only, and will override the <var>System.out</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>-stdout</code>.  If it is, there will be conflicts with
which process owns the file.</warn>

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