Logging

From Resin 3.0

(Difference between revisions)
Jump to: navigation, search
m (Log Configuration moved to Logging)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[Category:Configuration]]
 
[[Category:Configuration]]
  
−
Resin Configuration is at http://www.caucho.com/resin-3.0/config/log.xtp
+
== Access logging ==
  
−
Resin's <access-log> configures the URL access logging.  Its <log> configures the [java.util.logging] output.  Both share much of the common configuration.
+
{{main|access-log}}
  
−
==See Also==
+
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.
  
−
[[Redirecting Standard Output]]
+
See the main page for a description of all available configuration settings.
  
−
==rollover tags==
+
=== Examples ===
  
−
<[[access-log]]> shares the rollover configuration with the <log>.
+
<!-- pre -->
 +
<access-log path="logs/access.log"
 +
            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'
 +
            rollover-period="1W"/>
 +
<!-- /pre -->
  
−
{{:Log Rollover}}
+
<!-- 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==
 
  
−
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.
+
== stdout-log and stderr-log ==
  
−
archive-format uses the [[Date Format Configuration]] and [[Period Configuration]] syntax, for example:
+
{{main|stdout-log}}
 +
{{main|stderr-log}}
  
−
...
+
The stdout-log and stderr-log directives capture and redirect the output of
−
<host id="www.foo.com">
+
[[System.out]] and [[System.err]].
−
    <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.
+
=== Examples ===
  
−
<access-log path="log/access.log"
+
[[resin.conf]] configuration to capture [[System.out]] and [[System.err]]
−
            archive-path="/var/www/log/access.log.%Y%m%d.gz"
+
output to log files.
−
            rollover-period="1D"/>
+
  
−
==access-log ==
+
<!-- pre title="resin.conf" syntax="conf" -->
  
−
{{:access-log}}
+
&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'/>
 +
 
 +
  ...
  
−
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 -->
  
 +
== log ==
  
−
<access-log path="logs/access.log"
+
{{main|log}}
−
            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'
+
−
            rollover-period="1W"/>
+
  
−
==access-log format tags==
+
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.
−
||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>==
+
=== Examples ===
  
−
The <log> tag configures [[java.util.logging]] output.  It can appear in any [[Environment]].
+
resin.conf configuration to capture ''finer'' logging and display it on the
 +
console, useful during development:
  
−
By convention, the name of a logger is the class of the Java file that's logging, e.g. "com.caucho.server.port.Port".
+
<!--  pre -->
 +
<resin xmlns="http://caucho.com/ns/resin"
 +
        xmlns:resin="http://caucho.com/ns/resin/core">
 +
  ...
 +
  <log name="" level="finer" path="stdout:"/>
 +
  ...
 +
</resin>
 +
<!-- /pre -->
  
−
{|
+
resin.conf configuration to capture ''finer'' request and response related
−
||attribute||meaning||default
+
logging from Resin, and all logging from the ''com.hogwarts'' application under
−
|-
+
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 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>
 +
<!-- /pre -->
  
−
package com.foo;
+
== Archiving ==
−
+
−
import java.util.logging.Logger;
+
−
+
−
public class Test {
+
−
  private static final Logger log
+
−
    = Logger.getLogger(Test.class.getName());
+
−
+
−
  public void doStuff()
+
−
  {
+
−
    log.fine("doing stuff");
+
−
  }
+
−
}
+
  
 +
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. 
  
−
  <resin xmlns="http://caucho.com/ns/resin">
+
'''path-format''' and '''archive-format''' are two mutually exclusive methods
−
  <log name="com.foo" level="fine" path="log/debug.log"
+
for archiving logs. ''Rollover'' determines the frequency at which the archive
−
        timestamp="[%H:%M:%S] "/>
+
files are created.
−
  ...
+
 
−
  </resin>
+
=== 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

[edit] 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.

[edit] 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"/>


[edit] 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.

[edit] 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'/>
 
  ...


[edit] 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.

[edit] 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>

[edit] 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.

[edit] 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>
...

[edit] 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"/>

[edit] 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.

[edit] 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