docs/1.2/configuring-logging.html

Title: Configuring Logging

	
<P>Cayenne logging is based on Log4J package from Jakarta Apache Project. This is the most powerful and flexible logging framework available in Java. Log4J configuration is normally done using a property file. Later in this chapter we explain how Cayenne loads configuration files and how to customize this process. Format of the entries in this file is described in the Log4j documentation. Here is a sample configuration file contents:</P>

<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
<PRE># General Log4J stuff
log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=cayenne %-5p [%t %d{MM-dd HH:mm:ss}] %c{1}: %m%n

# indiv. packages configuration - turning on the packages that we care about
#log4j.logger.org.objectstyle.cayenne = INFO

# This is the logger that controls SQL output
# Setting the level to INFO or DEBUG will turn the logs on
log4j.logger.org.objectstyle.cayenne.access.QueryLogger = INFO
</PRE>
</DIV></DIV>

<DIV class="panelMacro"><TABLE class="infoMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="http://cayenne.apache.org/docs/1.2/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD><B>Users of Other Logging Frameworks</B><BR>If your application uses another package for its own logging purposes (like JDK 1.4 java.util.logging, or commons-logging from Jakarta), Cayenne Log4J-based logging will not interfere with your other logging configurations.</TD></TR></TABLE></DIV>

<DIV class="panelMacro"><TABLE class="tipMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="http://cayenne.apache.org/docs/1.2/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD><B>Log4J Users</B><BR>If your application already uses Log4J, Cayenne will simply use your existing configuration.</TD></TR></TABLE></DIV>

<H3><A name="ConfiguringLogging-EssentialLoggers"></A>Essential Loggers</H3>
<P>SQL Tracing. Very important logging feature of Cayenne is tracing the execution of SQL statements. If configured appropriately, Cayenne will log opened connections, executed queries, and DDL statements. This is extremely important in understanding what is going on in the application, tracing bugs, etc. Logger that is responsible for SQL logging is &quot;org.objectstyle.cayenne.access.QueryLogger&quot;. Its default logging level is INFO, so the following lines in the configuration file will turn it on or off:</P>

<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
<PRE># Turn SQL tracing on
log4j.logger.org.objectstyle.cayenne.access.QueryLogger = INFO

# Turn SQL tracing off, e.g. to increase performance
log4j.logger.org.objectstyle.cayenne.access.QueryLogger = WARN
</PRE>
</DIV></DIV>

<P>Tracing Configuration Loading. Cayenne XML files may contain errors, or maybe missing or inaccessible by the application; there maybe lots of other reasons why Cayenne fails to startup, from missing JDBC drivers to misspelled database URLs. To trace configuration loading process, you will need to turn on the following loggers:</P>

<DIV class="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
<PRE>log4j.logger.org.objectstyle.cayenne.conf = DEBUG
log4j.logger.org.objectstyle.cayenne.util = DEBUG
</PRE>
</DIV></DIV>

<H3><A name="ConfiguringLogging-DefaultConfiguration"></A>Default Configuration</H3>
<P>Default behaviour of Cayenne is to look for a file called cayenne-log.properties, first in the directory $HOME/.cayenne/, then in the CLASSPATH (i.e. a file called .cayenne/cayenne-log.properties at the root of one of the locations accessible by the ClassLoader). $HOME is a system specific home directory of a user running the application. If you don't know what it is, try printing it from Java like this: System.out.println(System.getProperty(&quot;user.home&quot;)).</P>

<P>If you don't explicitly create this file, Cayenne will use the one included in cayenne.jar (and therefore guaranteed to be in the CLASSPATH). This means - no special logging configuration is required, Cayenne will just work out of the box.</P>

<H3><A name="ConfiguringLogging-CustomConfigurationFile"></A>Custom Configuration File</H3>
<P>If you are not satisfied with the default location or default file name of the logging configuration, you can supply your own:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-comment">// Obtain the URL of the custom configuration file
</SPAN>java.net.URL url = ....;

<SPAN class="code-comment">// configure cayenne logging
</SPAN><SPAN class="code-comment">// note that URL can be <SPAN class="code-keyword">null</SPAN>, resulting in <SPAN class="code-keyword">default</SPAN> settings
</SPAN>org.objectstyle.cayenne.conf.Configuration.configureCommonLogging(url);
</PRE>
</DIV></DIV>
<P>It is important to execute this code before any calls to Cayenne are made in the application, or otherwise it will have no effect on logging.</P>

<H3><A name="ConfiguringLogging-ConfiguringLog4JoutsideofCayenne"></A>Configuring Log4J outside of Cayenne</H3>

<P>Finally, if your application already uses Log4J and implements its own logic to configure logging, it would be undesirable for Cayenne to use its default behavior and override any application settings. Also it is convenient to use a single logging configuration file per application. Cayenne detects if Log4J has already been started and will stop any attempts to configure logging. This means that Log4J services must be configured prior to any calls to Cayenne. </P>