Configuring the Logs

Basic Rules

As of release 3.8, Atomikos uses any existing logging frameworks found by these rules :

any implementation of SLF4J that can be found in the classpath (e.g., Logback), or
[4.0 and higher] if not found and Log4J2 is available on the classpath, then Log4J2 will be used, or
if not found and Log4J is available in the classpath, then Log4J will be used, or
otherwise, the built-in JDK logging is used

Log Levels

We use the following log level conventions:

Release 4.0 and higher

FATAL: situations that probably require 1st line support attention - like (re)start errors. You probably want to let Atomikos know about these.
ERROR: situations that require at least 2nd / 3rd line support attention - like heuristic exceptions. You probably want to let Atomikos know about these.
WARN: situations that require developer attention as soon as time allows. You probably want to let Atomikos know about these.
INFO: normal system messages indicating normal system operation.
DEBUG: shows what is going on across APIs so per-transaction details are shown. Only produce these when asked by Atomikos support.
TRACE: everything else, mostly inner workings of the Atomikos software. You probably only want these when asked by Atomikos support.

Pre-4.0

WARN: abnormal situations
INFO: shows what is going on across APIs so per-transaction details are shown
DEBUG: everything else

Tested Configuration Examples

Logback

Save the following file in your class path, under the name "logback.xml":

<configuration>

  <!-- Optional: to enable JMX setting of log levels 
       cf http://logback.qos.ch/manual/jmxConfig.html -->
  <jmxConfigurator/> 

  <appender name="ATOMIKOS" class="ch.qos.logback.core.FileAppender">
    <file>tm.out</file>
    <append>true</append>

    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
    </encoder>
  </appender>

 <!-- NOTE: logback does not support FATAL, only ERROR, WARN, INFO, DEBUG and TRACE -->
 <logger name="com.atomikos" level="DEBUG">
    <appender-ref ref="ATOMIKOS" />
  </logger>

</configuration>

This has been tested with log back 1.0.8. To try for yourself, add the following to your pom (or classpath):

                <dependency>
                        <groupId>org.slf4j</groupId>
                        <artifactId>slf4j-api</artifactId>
                        <version>1.7.2</version>
                </dependency>
                <dependency>
                        <groupId>ch.qos.logback</groupId>
                        <artifactId>logback-classic</artifactId>
                        <version>1.1.8</version>
                </dependency>
                <dependency>
                        <groupId>ch.qos.logback</groupId>
                        <artifactId>logback-core</artifactId>
                        <version>1.1.8</version>
                </dependency>

Log4J

Save the following file as "log4j.properties" on your classpath:

log4j.appender.Atomikos = org.apache.log4j.RollingFileAppender
log4j.appender.Atomikos.File = tm.out
log4j.appender.Atomikos.MaxFileSize = 100KB
log4j.appender.Atomikos.Append = false
log4j.appender.Atomikos.layout = org.apache.log4j.PatternLayout
log4j.appender.Atomikos.layout.ConversionPattern=%p %t %c - %m%n
log4j.logger.com.atomikos=DEBUG, Atomikos

Add the following jars to your pom (or classpath):

                <dependency>
                        <groupId>org.slf4j</groupId>
                        <artifactId>slf4j-api</artifactId>
                        <version>1.7.2</version>
                </dependency>
                <dependency>
                        <groupId>org.slf4j</groupId>
                        <artifactId>slf4j-log4j12</artifactId>
                        <version>1.7.2</version>
                </dependency>

JDK logging

The advantage of JDK logging is that you don't need extra jars in your classpath. However, it is a bit more difficult to configure.

Note: This solution seems to disallow a separate file for separate loggers. In order to reproduce a separate tm.out you would need a Tomcat/apache utility library - see http://tomcat.apache.org/tomcat-5.5-doc/logging.html

We've been able to run the following successfully:

# Set the default logging level for the logger named com.atomikos
# One of: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL, OFF
com.atomikos.level = FINE
com.atomikos.handlers = java.util.logging.FileHandler

java.util.logging.FileHandler.pattern=tm.out

java.util.logging.FileHandler.limit=50000

com.atomikos.useParentHandlers=false

java.util.logging.FileHandler.count=1
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

Then start your application with the following system property:

java ... -Djava.util.logging.config.file=<path to your properties file>

Tomcat Note

If you are using Tomcat, then the logging configuration (jars + configuration files) need to be at the same level as the atomikos jars. So if you have atomikos installed in the tomcat server lib folder, then the logging configuration should go there as well. Otherwise, it will not work.

Untested Configuration Examples

Log4J2

<Configuration package="log4j.test" status="WARN">
   <Appenders>
      <Console name="Console" target="SYSTEM_OUT">
         <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n" />
      </Console>
   </Appenders>
   <Loggers>
      <Logger name="com.atomikos" level="trace">
         <AppenderRef ref="Console" />
      </Logger>
      <Root level="trace">
         <AppenderRef ref="Console" />
      </Root>
   </Loggers>
</Configuration>

Logging with Spring Boot

See Spring Boot Integration for how to configure the logging with Spring Boot