This document describes how logging is implemented and how it can be
configured for the freebXML Registry and related clients.
The freebXML Registry relies on Apache
Commons-Logging for the logging abstraction. Furthermore, it is
deployed with Apache
Log4J, which is the first implementation choice for Commons-Logging.
Note: Consult 3rd party documentation for logging details on libraries used by the freebXML Registry.
This section briefly describes Commons Logging configuration.
Detailed information can be obtained from
Commons-Logging User Guide.
Commons-Logging uses 2 abstractions: Log (the logger)
and
LogFactory (which creates Log instances).
The Log implementation chosen by the default LogFactory
implementation is the first match on the following discovery process:
org.apache.commons.logging.Log
in resource commons-logging.properties. org.apache.commons.logging.LogOptionally, Commons-Logging can be turned off and produce no log at all
by setting org.apache.commons.logging.Log=org.apache.commons.logging.NoOpLog.
This section briefly describes Apache Log4J configuration. For detailed information, check Log4J Documentation.
Log4J is configured using system properties and/or a properties file
(log4j.properties, by default). Log4J accepts many hierarchically
configured Loggers (used by the source code to log
something) with the RootLogger residing on top of the
hierarchy. Loggers can be mapped to one or more appenders (which
actually write the log message that the user can see). Both Logger
and Appender can have a minimal Priority to
start logging. These are some relevant properties:
priority can be: DEBUG, INFO, WARN,
ERROR,
or FATAL.
appender corresponds to a configured output device.
logger.name corresponds to the parameter of LogFactory.getLog(logger.name),
used to create the logger instance. logger.name
could be a package name, for instance com.foo, which
would be a parent for a com.foo.Bar logger.
There are 3 basic situations where log can be configured for freebXML Registry: build time, server runtime and client runtime.
Some of the the targets in build scripts will use the apacheLog
variable to configure Commons-Logging. In build.xml, it is defined by
default to quiet mode like this:
<!-- A properties to control whether apache common
logging is enabled -->
<property name="apacheLog"
value="org.apache.commons.logging.impl.NoOpLog"/>
It should not be changed there, but in the build.properties file:
#Used to control apache common logging
#Use SimpleLog to have logging output
apacheLog=org.apache.commons.logging.impl.SimpleLog
//TODO: Give more information on using Log4J/selective package
logging here.
Note: This configures only the client side of the building process. For server side, see the next section.
Server side log is configured by commons-logging.properties
and (possibly)log4j.properties
resources present in classpath. These files can be found at:
<TOMCAT_HOME>/webapps/omar/WEB-INF/classes
By the time this
document was written, commons-logging.properties was
setting log to NoOpLog (quiet mode). In order to get
freebXMLRegistry Server to start producing log, change org.apache.commons.logging.Log
property value; check the file for other possibilities or comment the
property to fall back to Log4J.
Next you should decide the desired priority levels and appenders in log4j.properties.
Again, by the time this document was written, there were 2 appenders
configure, stdout (Console) and R (ebxmlrr.log
file in current directory), and priority was INFO. If you
need to debug the server, you could change the RootLogger (log4j.rootLogger
property) to trace or debug. Although, that
will generate a huge amount of unnecessary log that might be quite
difficult to follow. The solution for that is to add a new Logger just
for the class/package you want to debug. For instance, in order to
debug server security module, leave the RootLogger on INFO
and add the following line to the configuration:
log4j.logger.org.freebxml.omar.server.security=trace
Hint: If you want
Tomcat to redirect Console log messages generated by OMAR webapp to a
.log file in <TOMCAT_HOME>/logs, edit Tomcat server
configuration (<TOMCAT_HOME>/conf/server.xml) and
add a context like this:
<Context
path="/omar" docBase="omar" debug="0"
reloadable="true" crossContext="true" swallowOutput="true">
<Logger
className="org.apache.catalina.logger.FileLogger"
prefix="omar_log." suffix=".txt"
timestamp="true"/>
</Context>
This section is under construction.
//TODO: URGENT! reconsider choice and review this!
Client runtime log is similar to server in the sense that
Commons-Logging and Log4J are present (loaded by jaxr-ebxml.jar),
although there are a couple of basic differences:
commons-logging.properties
and log4j.properties
are currently packed in the client jars and can be in different jarsapacheLog
presented in Buil Log section will be in use.Help to write this section by throwing your questions to ebxmlrr-tech@lists.sourceforge.net.
Follow these steps (configuration files located in <TOMCAT_HOME>/webapps/omar/WEB-INF/classes):
commons-logging.properties. Make sure
property org.apache.commons.logging.Log
property in is commented or has value "org.apache.commons.logging.impl.Log4JLogger".log4j.properties. Add this line (or
change, if property exists):log4j.logger.org.freebxml.omar.server.interfaces.soap.RegistrySOAPServlet=traceNote: Currently uses the default platform charset for logging the
request / response message.
Follow these steps (configuration files located in <TOMCAT_HOME>/webapps/omar/WEB-INF/classes):
commons-logging.properties. Make sure
property org.apache.commons.logging.Log
property in is commented or has value "org.apache.commons.logging.impl.Log4JLogger".log4j.properties. Add the line (or
change, if property exists):log4j.logger.org.freebxml.omar.server.security.authorization.AuthorizationServiceImpl=tracelog4j.logger.org.freebxml.omar.server.security.authorization=traceFollow these steps (configuration files located in <TOMCAT_HOME>/webapps/omar/WEB-INF/classes):
commons-logging.properties. Make sure
property org.apache.commons.logging.Log
property in is commented or has value "org.apache.commons.logging.impl.Log4JLogger".log4j.properties. For tracing only the
DAO classes, add the line (or change, if property exists):log4j.logger.org.freebxml.omar.server.persistence.rdb.AbstractDAO=tracelog4j.logger.org.freebxml.omar.server.persistence=tracelog4j.logger.org.freebxml.omar.server.persistence.rdb=traceFollow these steps (configuration files located in <TOMCAT_HOME>/webapps/omar/WEB-INF/classes):
commons-logging.properties. Make sure
property org.apache.commons.logging.Log
property in is commented or has value "org.apache.commons.logging.impl.Log4JLogger".log4j.properties. Add the line (or
change, if property exists):log4j.logger.org.freebxml.omar.server.query.sql.SQLQueryProcessor=tracelog4j.logger.org.freebxml.omar.server.query.sql=trace