Cayenne User Documentation
Configuring Logging

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:

    # 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.apache.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.apache.cayenne.access.QueryLogger = INFO

| Users of Other Logging Frameworks 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.

| Log4J Users If your application already uses Log4J, Cayenne will simply use your existing configuration.

### Essential Loggers

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 "org.apache.cayenne.access.QueryLogger". Its default logging level is INFO, so the following lines in the configuration file will turn it on or off:

    # Turn SQL tracing on
    log4j.logger.org.apache.cayenne.access.QueryLogger = INFO

    # Turn SQL tracing off, e.g. to increase performance
    log4j.logger.org.apache.cayenne.access.QueryLogger = WARN

When SQL tracing is turned off, it is possible to log the execution of only certain queries or commits by manually increasing the logging level of just a specific query above the level configured for the QueryLogger. This is a very convenient feature for debugging the code, since it reduces the level of noise in the logs, focusing attention on the queries that are important. This API is discussed in the FAQ.

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:

    log4j.logger.org.apache.cayenne.conf = DEBUG
    log4j.logger.org.apache.cayenne.util = DEBUG

### Default Configuration

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("user.home")).

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.

### Custom Configuration File

If you are not satisfied with the default location or default file name of the logging configuration, you can supply your own:

    // Obtain the URL of the custom configuration file
    java.net.URL url = ....;

    // configure cayenne logging
    // note that URL can be null, resulting in default settings
    org.apache.cayenne.conf.Configuration.configureCommonLogging(url);

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.

### Configuring Log4J outside of Cayenne

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.

.
Copyright ©2001-2006 Apache Software Foundation