Log

From Resin 3.0

(Difference between revisions)
Jump to: navigation, search
 
(2 intermediate revisions by one user not shown)
Line 1: Line 1:
−
[[Category:Configuration]]
+
{{Cleanup}}
 +
[[Category:Directive]]
  
−
The <log> tag configures [[java.util.logging]] output.  It can appear in any [[Environment]].
+
The '''log''' directive configures {{javadoc|java.util.logging}} output.  It
 +
can appear in any [[environment]].
  
−
== tags ==
+
== Directives ==
−
By convention, the name of a logger is the class of the Java file that's logging, e.g. "com.caucho.server.port.Port".
+
  
 
{|
 
{|
−
||attribute||meaning||default
+
!directive||meaning||default
 
|-
 
|-
−
||name||logging name||required
+
||[[name]]
 +
||logging name
 +
||required, "" matches all names
 
|-
 
|-
−
||level||java.util.logging level||info
+
||[[level]]
 +
||severe, warning, info, config, fine, finer, finest
 +
||info
 
|-
 
|-
−
||timestamp||a timestamp to be used for logging||none
+
||[[path]]
 +
||output path for the stream
 +
||either <tt>path-format</tt> or <tt>path</tt> is required
 
|-
 
|-
−
||use-parent-handlers||if true, also write to the parent||true
+
||[[path-format]]
 +
||the name of a file to write the log to, [[date format]] escape sequences are replaced with the current date and time
 +
||either <tt>path</tt> or <tt>path-format</tt> is required
 
|-
 
|-
−
||handler||add a custom handler||
+
||[[rollover-period]]
 +
||how often to rollover the log.  Specify a [[period]] in days (15D), weeks (2W), months (1M), or hours (1h)
 +
||none
 
|-
 
|-
−
||formatter||add a custom formatter||
+
||[[rollover-size]]
 +
||maximum size of the file before a rollover occurs.  Specify a [[size]] in bytes (50000), kb (128kb), or megabytes (10mb)
 +
||1mb
 
|-
 
|-
−
||mbean-name||save in jmx||
+
||[[archive-format]]
 +
||the format for the archive filename when a rollover occurs
 +
|| ''path'' + ".%Y%m%d" or ''path'' + ".%Y%m%d.%H" if <tt>rollover-period</tt> &lt; 1 day
 
|-
 
|-
−
||path||output path (see above)||required
+
||[[timestamp]]
 +
||a timestamp in [[date format]] to use at the beginning of each log line.
 +
||no timestamp
 
|-
 
|-
−
||path-format||formatted path (see above)||
+
||[[format]]
 +
||a format string for each log message
 +
||just the log message
 
|-
 
|-
−
||archive-format||format of the archive (see above)||
+
||[[use-parent-handlers]]
 +
||if true, also write to the parent
 +
||true
 
|-
 
|-
−
||rollover-period||how often to rollover (see above)||
+
||[[handler]]
 +
||add a custom handler
 +
||
 +
|-
 +
||[[formatter]]
 +
||add a custom formatter
 +
||
 +
|-
 +
||[[mbean-name]]
 +
||save in jmx
 +
||
 
|-
 
|-
−
||rollover-size||how large a file before rolling over (see above)||
 
 
|}
 
|}
  
−
The timestamp uses the [[Date Format Configuration]] syntax.
+
== Level ==
−
 
+
−
== Example Logging Usage ==
+
−
 
+
−
package com.foo;
+
−
+
−
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");
+
−
  }
+
−
}
+
−
 
+
−
 
+
−
<resin xmlns="http://caucho.com/ns/resin">
+
−
  <log name="com.foo" level="fine" path="log/debug.log"
+
−
        timestamp="[%H:%M:%S] "/>
+
−
  ...
+
−
</resin>
+
−
 
+
−
== Logging Level Conventions ==
+
  
 
Conventions on logging levels:
 
Conventions on logging levels:
  
 
{|
 
{|
−
||level||use
+
!level||use
 
|-
 
|-
−
||warning||fatal errors
+
||severe
 +
||a serious failure, likely to prevent normal program execution
 
|-
 
|-
−
||info||information for a typical install
+
||warning
 +
||an unexpected error that indicates there is a problem, program execution may or may not continue
 +
|-
 +
||info
 +
||information for a typical install
 +
|-
 +
||config
 +
||static configuration messages, meant to assist in debugging problems associated with particular configurations
 
|-
 
|-
 
||fine||debug information useful for users
 
||fine||debug information useful for users
 
|-
 
|-
 
||finer||debug information useful for developers
 
||finer||debug information useful for developers
 +
|-
 +
||finest||verbose debug information useful for developers of a particular module
 
|}
 
|}
  
−
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.
+
For example, level="fine" for "com.caucho" will give the information most
 +
generally useful for Resin users, while level="finer" will add information
 +
that's more detailed for the Caucho developers.  Messages at level="info" are
 +
infrequent, giving significant information like the server starting.
  
 +
== Name ==
  
−
== Log Names ==
+
By convention, the name of a logger is the class of the Java file that's
 +
logging, e.g. "com.caucho.server.port.Port".
  
−
{{:Resin Logging Names}}
+
{{:Resin logging names}}
  
−
== Specifying Logs For Different Environments ==
+
=== Multiple names for one destination ===
  
−
Resin lets you configure individual logs for each [[environment]], e.g. separate logs for <[[web-app]]> or <[[host]]>.  To enable the logs, just add the <log> tag in the environment.
+
<tt>log</tt> can contain multiple logger directives:
 +
 
 +
<!-- pre -->
 +
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
 +
    &lt;!-- log request and response info --&gt;
 +
    &lt;log path='stdout:' timestamp='[%H:%M:%S.%s] '&gt;
 +
      &lt;logger name="com.caucho.server.port.TcpConnection" level="fine"/&gt;
 +
      &lt;logger name="com.caucho.server.http.HttpRequest" level="fine"/&gt;
 +
      &lt;logger name="com.caucho.server.connection.AbstractHttpResponse" level="fine"/&gt;
 +
    &lt;/log&gt;
 +
    ...
 +
&lt;/resin&gt;
 +
<!-- /pre -->
 +
 
 +
== Environments ==
 +
 
 +
<tt>log</tt> can appear in any [[environment]] (i.e. within a [[server]],
 +
[[host]], or [[web-app]]).
  
 
=== resin-web.xml ===
 
=== resin-web.xml ===
Line 95: Line 132:
 
   ...
 
   ...
 
  </web-app>
 
  </web-app>
 +
 +
== format ==
 +
 +
The '''format''' for log tags is used to specify a format string for each log
 +
message.  <tt>format</tt> recognizes EL-expressions. The EL variable ''log'' is
 +
a {{javadoc|com.caucho.log.ELFormatter.ELFormatterLogRecord}}.
 +
 +
<!-- pre -->
 +
&lt;log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
 +
      format=" ${log.level} ${log.loggerName} ${log.message}"/&gt;
 +
<!-- /pre -->
 +
 +
{|
 +
!accessor||value
 +
|-
 +
||${log.level}
 +
||The level of the log record
 +
|-
 +
||${log.name}
 +
||The source loggers name
 +
|-
 +
||${log.shortName}
 +
||A shorter version of the source loggers name, "Foo" instead of "com.hogwarts.Foo"
 +
|-
 +
||${log.message}
 +
||The message, with no formatting or localization
 +
|-
 +
||${log.millis}
 +
||event time in milliseconds since 1970
 +
|-
 +
||${log.sourceClassName}
 +
||Get the name of the class that issued the logging request (may not be available at runtime)
 +
|-
 +
||${log.sourceMethodName}
 +
||Get the name of the method that issued the logging request (may not be available at runtime)
 +
|-
 +
||${log.threadID}
 +
||Get an ''int'' identifier of the thread where the logging request originated
 +
|-
 +
||${log.thrown}
 +
||Get any {{javadoc|java.lang.Throwable}} associated with the logging request
 +
|}
 +
 +
 +
You can also use the [[environment EL variables]] in your format string:
 +
 +
<!-- pre -->
 +
  &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;
 +
<!-- /pre -->
 +
 +
<!-- pre -->
 +
[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
 +
<!-- /pre -->
 +
 +
The [[fmt.sprintf()]] function can
 +
space pad the values and make the results look a little nicer:
 +
 +
<!-- pre -->
 +
<log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
 +
      format=" ${fmt.sprintf('%-7s %45s %s',log.level,log.loggerName,log.message)}"/>
 +
<!-- /pre -->
 +
 +
<!-- pre -->
 +
[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
 +
<!-- /pre -->
 +
 +
[[fmt.sprintf()]] and [[fmt.timestamp()]] can be used to produce CSV files:
 +
 +
<!-- pre -->
 +
<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)}"/>
 +
<!-- /pre -->
 +
 +
<!-- pre -->
 +
"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"
 +
<!-- /pre -->
 +
 +
== Unix syslog ==
 +
 +
On Unix systems, the SyslogHandler lets you log messages to syslog.
 +
 +
<!-- pre -->
 +
&lt;log name="" level="warning">
 +
  &lt;handler resin:type="com.caucho.log.SyslogHandler">
 +
    &lt;facility>daemon&lt;/facility>
 +
    &lt;severity>notice&lt;/severity>
 +
  &lt;/handler>
 +
&lt;/log>
 +
<!-- /pre -->
 +
 +
The possible values for ''facility'' are user, mail, daemon, auth, lpr,
 +
news, uucp, cron, authpriv, ftp, local0, local1, local2, local3, local4,
 +
local5, local6, local7. The default is ''daemon''.
 +
 +
The possible values for ''severity'' are emerg, alert, crit, err,
 +
warning, notice, info, debug. The default is ''info''.
 +
 +
See also `<tt>man 3 syslog</tt>' and `<tt>man syslog.conf</tt>'.
 +
 +
== Example logging usage in your application ==
 +
 +
Application developers can take advantage of the JDK logging facilities and
 +
Resin's flexible handling of log messages.
 +
 +
<!-- pre -->
 +
package com.foo;
 +
 +
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");
 +
  }
 +
}
 +
<!-- /pre -->
 +
 +
 +
<!-- pre -->
 +
<resin xmlns="http://caucho.com/ns/resin">
 +
  <log name="com.foo" level="fine" path="log/debug.log"
 +
        timestamp="[%H:%M:%S] "/>
 +
  ...
 +
</resin>
 +
<!-- /pre -->
 +
 +
== See also ==
 +
 +
; [[Logging]] : A general overview of logging facilities in Resin

Latest revision as of 16:19, 7 December 2011

40px-Edit-clear.png This article requires cleanup and may refer to a legacy version of Resin.

Please visit http://www.caucho.com/documentation/ for the most up-to-date documentation.

The log directive configures java.util.logging output. It can appear in any environment.

Contents

[edit] Directives

directive meaning default
name logging name required, "" matches all names
level severe, warning, info, config, fine, finer, finest info
path output path for the stream either path-format or path is required
path-format the name of a file to write the log to, date format escape sequences are replaced with the current date and time either path or path-format is required
rollover-period how often to rollover the log. Specify a period in days (15D), weeks (2W), months (1M), or hours (1h) none
rollover-size maximum size of the file before a rollover occurs. Specify a size in bytes (50000), kb (128kb), or megabytes (10mb) 1mb
archive-format the format for the archive filename when a rollover occurs path + ".%Y%m%d" or path + ".%Y%m%d.%H" if rollover-period < 1 day
timestamp a timestamp in date format to use at the beginning of each log line. no timestamp
format a format string for each log message just the log message
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

[edit] Level

Conventions on logging levels:

level use
severe a serious failure, likely to prevent normal program execution
warning an unexpected error that indicates there is a problem, program execution may or may not continue
info information for a typical install
config static configuration messages, meant to assist in debugging problems associated with particular configurations
fine debug information useful for users
finer debug information useful for developers
finest verbose debug information useful for developers of a particular module

For example, level="fine" for "com.caucho" will give the information most generally useful for Resin users, while level="finer" will add information that's more detailed for the Caucho developers. Messages at level="info" are infrequent, giving significant information like the server starting.

[edit] Name

By convention, the name of a logger is the class of the Java file that's logging, e.g. "com.caucho.server.port.Port".

40px-Edit-clear.png This article requires cleanup and may refer to a legacy version of Resin.

Please visit http://www.caucho.com/documentation/ for the most up-to-date documentation.

Resin's logging convention uses the class name to as the java.util.logging name.

name meaning
com.caucho all Caucho logging
com.caucho.server.port Port listening and accepts
com.caucho.server.cache proxy caching
com.caucho.server.session sessions
com.caucho.server.cluster clustering and persistent sessions
com.caucho.server.webapp <web-app> support
com.caucho.server.host <host> support
com.caucho.server.e_app .ear file support
com.caucho.server.resin top-level container support, i.e. <resin> and <server>
com.caucho.server.http http protocol support
com.caucho.server.security authentication
com.caucho.jca JCA pooling
com.caucho.sql Database pooling (also see com.caucho.jca)
com.caucho.java Internal compilation
com.caucho.jsp JSP
com.caucho.amber Amber
com.caucho.ejb EJB
com.caucho.jmx JMX
com.caucho.loader Class Loading
com.caucho.jms JMS

[edit] Multiple names for one destination

log can contain multiple logger directives: 

<resin xmlns="http://caucho.com/ns/resin">
   <!-- 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"/>
   </log>
   ...
</resin>

[edit] Environments

log can appear in any environment (i.e. within a server, host, or web-app).

[edit] resin-web.xml 

<web-app xmlns="http://caucho.com/ns/resin">
   <log name="com.caucho.server.webapp"
           level="warning"
           path="WEB-INF/logs/error-log"/>

  ...
</web-app>

[edit] format

The format for log tags is used to specify a format string for each log message. format recognizes EL-expressions. The EL variable log is a com.caucho.log.ELFormatter.ELFormatterLogRecord. 

<log name= level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
     format=" ${log.level} ${log.loggerName} ${log.message}"/>
accessor value
${log.level} The level of the log record
${log.name} The source loggers name
${log.shortName} A shorter version of the source loggers name, "Foo" instead of "com.hogwarts.Foo"
${log.message} The message, with no formatting or localization
${log.millis} event time in milliseconds since 1970
${log.sourceClassName} Get the name of the class that issued the logging request (may not be available at runtime)
${log.sourceMethodName} Get the name of the method that issued the logging request (may not be available at runtime)
${log.threadID} Get an int identifier of the thread where the logging request originated
${log.thrown} Get any java.lang.Throwable associated with the logging request


You can also use the environment EL variables in your format string: 

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

[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[1] starting

The fmt.sprintf() function can space pad the values and make the results look a little nicer: 

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

[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

fmt.sprintf() and fmt.timestamp() can be used to produce CSV files: 

<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)}"/>

"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[2] starting"

[edit] Unix syslog

On Unix systems, the SyslogHandler lets you log messages to syslog. 

<log name="" level="warning"> 
  <handler resin:type="com.caucho.log.SyslogHandler">
    <facility>daemon</facility>
    <severity>notice</severity>
  </handler>
</log>

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

The possible values for severity are emerg, alert, crit, err, warning, notice, info, debug. The default is info.

See also `man 3 syslog' and `man syslog.conf'.

[edit] Example logging usage in your application

Application developers can take advantage of the JDK logging facilities and Resin's flexible handling of log messages. 

package com.foo;

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");
  }
}



<resin xmlns="http://caucho.com/ns/resin">
  <log name="com.foo" level="fine" path="log/debug.log"
       timestamp="[%H:%M:%S] "/>
  ...
</resin>

[edit] See also

Logging 
A general overview of logging facilities in Resin
Retrieved from "http://wiki3.caucho.com/index.php?title=Log&oldid=4331"
Personal tools