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.


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

Tested Configuration Examples


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

  <!-- Optional: to enable JMX setting of log levels 
       cf -->

  <appender name="ATOMIKOS" class="ch.qos.logback.core.FileAppender">

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

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


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


Save the following file as "" 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, Atomikos

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


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

We've been able to run the following successfully:

# Set the default logging level for the logger named com.atomikos
com.atomikos.level = FINE
com.atomikos.handlers = java.util.logging.FileHandler





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


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

Logging with Spring Boot

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

Contact Us

Atomikos Corporate Headquarters
Hoveniersstraat, 39/1, 2800
Mechelen, Belgium

T +3215613055

Subscribe to our newsletter

Never miss an update

Copyright 2021 Atomikos BVBA | Our Privacy Policy
By using this site you agree to our cookies. More info. That's Fine