Logging

From Resin 3.0

(Difference between revisions)
Jump to: navigation, search
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
Resin Configuration is at [config/log.xtp@resin-doc]
+
[[Category:Configuration]]
  
−
Resin's <access-log> configures the URL access logging.  Its <log> configures the [java.util.logging] output.  Both share much of the common configuration.
+
== Access logging ==
  
−
==See Also==
+
{{main|access-log}}
  
−
[[Redirecting Standard Output]]
+
An access log receives output describing each request received by
 +
the server.  It is commonly used in conjunction with analysis tools to
 +
determine statistics and patterns of use for a website.
  
−
==rollover tags==
+
See the main page for a description of all available configuration settings.
  
−
<access-log> shares the rollover configuration with the <log>.
+
=== Examples ===
  
−
{{Log Rollover}}
+
<!-- pre -->
 +
<access-log path="logs/access.log"
 +
            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'
 +
            rollover-period="1W"/>
 +
<!-- /pre -->
  
−
==archive-format and path-format==
+
<!-- pre -->
 +
<access-log path="logs/access.log"
 +
            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'
 +
            rollover-size="1mb"/>
 +
<!-- /pre -->
  
−
archive-format and path-format are two mutually exclusive methods for archiving logs.  path-format writes directly to the archive log, e.g. archive-2005-01-02.log.  archive-format first writes to a log specified by <em>path</em>, e.g. access.log and then copies the access.log to the archive name at rollover time.
 
  
−
archive-format uses the [[Date Format Configuration]] and [[Period Configuration]] syntax, for example:
+
== stdout-log and stderr-log ==
  
−
...
+
{{main|stdout-log}}
−
<host id="www.foo.com">
+
{{main|stderr-log}}
−
    <access-log path-format="/var/www/log/%Y/%m/%d.access.log"
+
−
                rollover-period="1D"/>
+
−
    ...
+
−
</host>
+
−
...
+
  
−
The archive-format can use a *.gz or *.zip extension to indicate that the archived log should be compressed.  Currently, path-format cannot be compressed.
+
The stdout-log and stderr-log directives capture and redirect the output of
 +
[[System.out]] and [[System.err]].
  
−
<access-log path="log/access.log"
+
=== Examples ===
−
            archive-path="/var/www/log/access.log.%Y%m%d.gz"
+
−
            rollover-period="1D"/>
+
  
−
==access-log ==
+
[[resin.conf]] configuration to capture [[System.out]] and [[System.err]]
 +
output to log files.
  
−
The <access-log> tag controls the information Resin prints with each request.   It can appear in any of the [[Server Configuration|<server>]], [[Host Configuration|<host>]], or <[[web-app]] environments.
+
<!-- pre title="resin.conf" syntax="conf" -->
  
 +
&lt;resin xmlns="http://caucho.com/ns/resin"
 +
        xmlns:resin="http://caucho.com/ns/resin/core"&gt;
 +
 +
  &lt;stdout-log path='/var/log/foo/stdout.log'
 +
              rollover-period='1W'/>
 +
  &lt;stderr-log path='/var/log/foo/stderr.log'
 +
              rollover-period='1W'/>
 +
 
 +
  ...
  
−
<access-log path="logs/access.log"
+
<!-- /pre -->
−
            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'
+
−
            rollover-period="1W"/>
+
  
−
==access-log format tags==
+
== log ==
  
−
{|
+
{{main|log}}
−
||code||meaning
+
−
|-
+
−
||%b||content length
+
−
|-
+
−
||%h||remote IP address
+
−
|-
+
−
||%\{xxx}i||request header xxx
+
−
|-
+
−
||%\{xxx}o||response header xxx
+
−
|-
+
−
||%\{xxx}c||cookie value xxx
+
−
|-
+
−
||%n||request attribute
+
−
|-
+
−
||%r||request URL
+
−
|-
+
−
||%s||status code
+
−
|-
+
−
||%\{xxx}t||date with optional time format
+
−
|-
+
−
||%T||time of request in seconds
+
−
|-
+
−
||%D||time of request in microseconds (3.0.15)
+
−
|-
+
−
||%u||remote user
+
−
|-
+
−
||%U||request URL
+
−
|}
+
  
−
==<log>==
+
Java programs (including Resin) can use the logging facilities included in the
 +
JDK.  Log messages have a ''name'' and and a ''level''.
  
−
The <log> tag configures [[java.util.logging]] output.  It can appear in any [[Environment]].
+
Logging can be used to enable [[Resin logging names]] and to enable application specific logging that utilizes the JDK logging facilities.
  
−
By convention, the name of a logger is the class of the Java file that's logging, e.g. "com.caucho.server.port.Port".
+
=== Examples ===
  
−
{|
+
resin.conf configuration to capture ''finer'' logging and display it on the
−
||attribute||meaning||default
+
console, useful during development:
−
|-
+
−
||name||logging name||required
+
−
|-
+
−
||level||java.util.logging level||info
+
−
|-
+
−
||timestamp||a timestamp to be used for logging||none
+
−
|-
+
−
||use-parent-handlers||if true, also write to the parent||true
+
−
|-
+
−
||handler||add a custom handler||
+
−
|-
+
−
||formatter||add a custom formatter||
+
−
|-
+
−
||mbean-name||save in jmx||
+
−
|-
+
−
||path||output path (see above)||required
+
−
|-
+
−
||path-format||formatted path (see above)||
+
−
|-
+
−
||archive-format||format of the archive (see above)||
+
−
|-
+
−
||rollover-period||how often to rollover (see above)||
+
−
|-
+
−
||rollover-size||how large a file before rolling over (see above)||
+
−
|}
+
  
−
The timestamp uses the [[Date Format Configuration]] syntax.
+
<!--  pre -->
 +
<resin xmlns="http://caucho.com/ns/resin"
 +
        xmlns:resin="http://caucho.com/ns/resin/core">
 +
  ...
 +
  <log name="" level="finer" path="stdout:"/>
 +
  ...
 +
</resin>
 +
<!-- /pre -->
  
−
package com.foo;
+
resin.conf configuration to capture ''finer'' request and response related
−
+
logging from Resin, and all logging from the ''com.hogwarts'' application under
−
import java.util.logging.Logger;
+
development:
−
+
−
public class Test {
+
−
  private static final Logger log
+
−
    = Logger.getLogger(Test.class.getName());
+
−
+
−
  public void doStuff()
+
−
  {
+
−
    log.fine("doing stuff");
+
−
  }
+
−
}
+
  
−
 
+
<!-- pre -->
−
  <resin xmlns="http://caucho.com/ns/resin">
+
  <resin xmlns="http://caucho.com/ns/resin"
−
   <log name="com.foo" level="fine" path="log/debug.log"
+
        xmlns:resin="http://caucho.com/ns/resin/core">
−
        timestamp="[%H:%M:%S] "/>
+
 
 +
   <!-- log request and response info -->
 +
  <log path='stdout:' timestamp='[%H:%M:%S.%s] '>
 +
    <logger name="com.caucho.server.port.TcpConnection" level="fine"/>
 +
    <logger name="com.caucho.server.http.HttpRequest" level="fine"/>
 +
    <logger name="com.caucho.server.connection.AbstractHttpResponse" level="fine"/>
 +
 
 +
    <logger name="com.hogwarts" level="all"/>
 +
  </log>
 +
 
 
   ...
 
   ...
 +
 
 
  </resin>
 
  </resin>
 +
<!-- /pre -->
 +
 +
== Archiving ==
 +
 +
All log directives support archiving, when the log reaches a certain size or
 +
age a rollover occurs and the existing log is saved away while a new log is
 +
started. 
 +
 +
'''path-format''' and '''archive-format''' are two mutually exclusive methods
 +
for archiving logs.  ''Rollover'' determines the frequency at which the archive
 +
files are created.
 +
 +
=== path-format ===
 +
 +
<tt>path-format</tt> specifies the name of a file. The name contains
 +
[[date format]]  escape sequences that are replaced with the current date and
 +
time.  When the rollover occurs, a new file is started with the appropriate
 +
date and time.  Thus <tt>path-format</tt> results in archive files that are
 +
named with the date and time of the first entry in the log.
 +
 +
...
 +
<host id="www.foo.com">
 +
    <access-log path-format="/var/www/log/%Y/%m/%d.access.log"
 +
                rollover-period="1D"/>
 +
    ...
 +
</host>
 +
...
 +
 +
=== archive-format and path ===
 +
 +
Log messages are written to the file specified by <tt>[[path]]</tt>.
 +
When a rollover occurs the contents of the file are copied to the
 +
<tt>archive-path</tt>.  The <tt>archive-path</tt> contains [[date format]]
 +
escape sequences that are replaced with the current date and time.  Thus
 +
archive-format results in log files that are named with the date and time of
 +
the last entry in the log.
 +
 +
archive-format can use a *.gz or *.zip extension to indicate that the
 +
archived log should be compressed.
 +
 +
<access-log path="log/access.log"
 +
            archive-path="/var/www/log/access.log.%Y%m%d.gz"
 +
            rollover-period="1D"/>
 +
 +
=== Rollover ===
  
−
Conventions on logging levels:
+
The fequency of the rollover is is specified with [[rollover-period]] or
 +
[[rollover-size]].
  
−
{|
+
<tt>rollover-period</tt> is a time based specification of a [[period]] in days
−
||level||use
+
(15D), weeks (2W), months (1M), or hours (1h).  When the specified time period
−
|-
+
has elapsed the rollover occurs.
−
||warning||fatal errors
+
−
|-
+
−
||info||information for a typical install
+
−
|-
+
−
||fine||debug information useful for users
+
−
|-
+
−
||finer||debug information useful for developers
+
−
|}
+
  
−
For example, level="fine" for "com.caucho" will give the information most generally useful for Resin uses, while level="finer" will add more information that's more detailed for the Caucho developers.  level="info" is infrequent, giving significant information like the server starting.
+
<tt>rollover-size</tt> is a size based specification of a [[size]] in bytes
 +
(50000), kb (128kb), or megabytes (10mb). When the log reaches the specified
 +
size the rollover occurs.
  
−
Some [[Resin Logging Names]] have been documented.
+
=== Disabling rollover ===
  
−
==stdout-log and stderr-log==
+
To completely disable rollovers, set the rollover-size to such a high number
 +
that it will never occur:
  
−
Resin can redirect the output of System.out and System.err using the <stdout-log> and <stderr-log> configuration in any [[Environment]]. The <stdout-log> and <stderr-log> use the same configuration as the <log> for rollover and archive paths.
+
<!-- pre -->
 +
  <stdout-log path="log/stdout.log" rollover-size="1024mb"/>
 +
<!-- /pre -->

Latest revision as of 19:54, 10 July 2008


Contents

Access logging

Main article: access-log

An access log receives output describing each request received by the server. It is commonly used in conjunction with analysis tools to determine statistics and patterns of use for a website.

See the main page for a description of all available configuration settings.

Examples 

<access-log path="logs/access.log"
            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'
            rollover-period="1W"/>

<access-log path="logs/access.log"
            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'
            rollover-size="1mb"/>


stdout-log and stderr-log

Main article: stdout-log
Main article: stderr-log

The stdout-log and stderr-log directives capture and redirect the output of System.out and System.err.

Examples

resin.conf configuration to capture System.out and System.err output to log files. 


<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">

  <stdout-log path='/var/log/foo/stdout.log'
              rollover-period='1W'/>
  <stderr-log path='/var/log/foo/stderr.log'
              rollover-period='1W'/>
 
  ...


log

Main article: log

Java programs (including Resin) can use the logging facilities included in the JDK. Log messages have a name and and a level.

Logging can be used to enable Resin logging names and to enable application specific logging that utilizes the JDK logging facilities.

Examples

resin.conf configuration to capture finer logging and display it on the console, useful during development: 

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  ...
  <log name="" level="finer" path="stdout:"/>
  ...
</resin>

resin.conf configuration to capture finer request and response related logging from Resin, and all logging from the com.hogwarts application under development: 

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
 
  <log path='stdout:' timestamp='[%H:%M:%S.%s] '>
    <logger name="com.caucho.server.port.TcpConnection" level="fine"/>
    <logger name="com.caucho.server.http.HttpRequest" level="fine"/>
    <logger name="com.caucho.server.connection.AbstractHttpResponse" level="fine"/>
 
    <logger name="com.hogwarts" level="all"/>
  </log>
 
  ...
  
</resin>

Archiving

All log directives support archiving, when the log reaches a certain size or age a rollover occurs and the existing log is saved away while a new log is started.

path-format and archive-format are two mutually exclusive methods for archiving logs. Rollover determines the frequency at which the archive files are created.

path-format

path-format specifies the name of a file. The name contains date format escape sequences that are replaced with the current date and time. When the rollover occurs, a new file is started with the appropriate date and time. Thus path-format results in archive files that are named with the date and time of the first entry in the log. 

...
<host id="www.foo.com">
   <access-log path-format="/var/www/log/%Y/%m/%d.access.log"
               rollover-period="1D"/>
   ... 
</host>
...

archive-format and path

Log messages are written to the file specified by path. When a rollover occurs the contents of the file are copied to the archive-path. The archive-path contains date format escape sequences that are replaced with the current date and time. Thus archive-format results in log files that are named with the date and time of the last entry in the log.

archive-format can use a *.gz or *.zip extension to indicate that the archived log should be compressed. 

<access-log path="log/access.log"
            archive-path="/var/www/log/access.log.%Y%m%d.gz"
            rollover-period="1D"/>

Rollover

The fequency of the rollover is is specified with rollover-period or rollover-size.

rollover-period is a time based specification of a period in days (15D), weeks (2W), months (1M), or hours (1h). When the specified time period has elapsed the rollover occurs.

rollover-size is a size based specification of a size in bytes (50000), kb (128kb), or megabytes (10mb). When the log reaches the specified size the rollover occurs.

Disabling rollover

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

 <stdout-log path="log/stdout.log" rollover-size="1024mb"/>
Retrieved from "http://wiki3.caucho.com/index.php?title=Logging&oldid=2878"
Personal tools