|
This document shows the prefered method for using the
Log4j logging
system inside of JBoss.
Using Logging
The first thing you need to decide is what is the category name your going
to use. This should be based on the class name of the component doing
the logging. If there are multiple instances of a component, and it is
associated with another meaningful name, this name will be
added as a subcategory to the component class name. For example,
the org.jboss.security.plugins.JaasSecurityManager class uses
a base category name equal to its class name. There can be
multiple JaasSecurityManager instances, and each is associated
with a security domain name. Therefore, the complete Log4j
category name used by the JaasSecurityManager is
org.jboss.security.plugins.JaasSecurityManager.securityDomain,
where the securityDomain value is the name of the associated
security domain.
To create a Logger for JaasSecurityManager this is
the code snippet:
After that just use the log with whatever priority level is approriate.
Priority Usage Recommendations
- TRACE
- Use TRACE the level priority for log messages
that are directly associated with activity that corresponds requests.
Further, such messages should not be submitted to a Logger unless the
Logger category priority threshold indicates that the message will be
rendered. Use the
Logger.isTraceEnabled() method to
determine if the category priority threshold is enabled. The point of
the TRACE priority is to allow for deep probing of the JBoss
server behavior when necessary. When the TRACE level priority
is enabled, you can expect the number of messages in the JBoss server
log to grow at least a x N, where N is the number of
requests received by the server, a some constant. The server log may
well grow as power of N depending on the request-handling layer
being traced.
- DEBUG
- Use the DEBUG level priority for log messages
that convey extra information regarding life-cycle events. Developer or
in depth information required for support is the basis for this priority.
The important point is that when the DEBUG level priority is
enabled, the JBoss server log should not grow proportionally with the
number of server requests. Looking at the DEBUG and
INFO messages for a given service category
should tell you exactly what state the service is in, as well as what
server resources it is using: ports, interfaces, log files, etc.
- INFO
- Use the INFO level priority for service
life-cycle events and other crucial related information. Looking at
the INFO messages for a given service category should tell you
exactly what state the service is in.
- WARN
- Use the WARN level priority for events that may
indicate a non-critical service error. Resumable errors, or minor breaches
in request expectations fall into this category. The distinction between
WARN and ERROR may be hard to discern and so its up to
the developer to judge.
The simplest criterion is would this failure result in a user support
call. If it would use ERROR. If it would not use WARN.
- ERROR
- Use the ERROR level priority for events
that indicate a disruption in a request or the ability to service a request.
A service should have some capacity to continue to service
requests in the presence of ERRORs.
- FATAL
- Use the FATAL level priority for events that
indicate a critical service failure. If a service issues a FATAL
error it is completely unable to service requests of any kind.
Activating the TRACE Priority
Activating the TRACE level priority is done by adding a
category threshold statement to the log4j.xml file.
To enable tracing for a particular JaasSecurityManager security
domain called other add:
<![CDATA[
<category name="org.jboss.security.plugins.JaasSecurityManager.other">
<priority value="TRACE" class="org.jboss.logging.XLevel"/>
</category>
]]>
To enable the TRACE level priority for all
JaasSecurityManager instances add:
<![CDATA[
<category name="org.jboss.security.plugins.JaasSecurityManager">
<priority value="TRACE" class="org.jboss.logging.XLevel"/>
</category>
]]>
To enable the TRACE level priority for all components in the
security package:
<![CDATA[
<category name="org.jboss.security">
<priority value="TRACE" class="org.jboss.logging.XLevel"/>
</category>
]]>
You can also redirect a given categories message to a seperate log
file or endpoint by assiging it a different appender. For example,
to redirect all security output to a security.log file,
and set the security package threshold to TRACE use:
<![CDATA[
<appender name="SECURIRTYLOG" class="org.apache.log4j.FileAppender">
<param name="File" value="${jboss.home}/log/security.log"/>
<param name="Append" value="false"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
</layout>
</appender>
<category name="org.jboss.security">
<priority value="TRACE" class="org.jboss.logging.XLevel"/>
<appender-ref ref="SECURIRTYLOG"/>
</category>
]]>
For properties style configuration (via log4j.properties):
log4j.category.org.jboss.security.plugins.JaasSecurityManager.other=\
TRACE#org.jboss.logging.XLevel
To enable the TRACE level priority for all
JaasSecurityManager instances add:
log4j.category.org.jboss.security.plugins.JaasSecurityManager=\
TRACE#org.jboss.logging.XLevel
To enable the TRACE level priority for all components in the
security package:
log4j.category.org.jboss.security=\
TRACE#org.jboss.logging.XLevel
You can also redirect a given categories message to a seperate log
file or endpoint by assiging it a different appender. For example,
to redirect all security output to a security.log file,
and set the security package threshold to TRACE use:
### The security.log file appender
log4j.appender.SecurityLog=org.apache.log4j.FileAppender
log4j.appender.SecurityLog.File=${jboss.home}/log/security.log
log4j.appender.SecurityLog.layout=org.apache.log4j.PatternLayout
log4j.appender.SecurityLog.layout.ConversionPattern=[%c{1}] %m%n
log4j.appender.SecurityLog.Append=false
log4j.category.org.jboss.security=\
TRACE#org.jboss.logging.XLevel, SecurityLog
|
