DataStax Java Driver

Logging

Quick overview

based on SLF4J.
config file examples for Logback and Log4J.

The driver uses SLF4J as a logging facade. This allows you to plug in your preferred logging framework (java.util.logging, logback, log4j…) at deployment time.

Setup

To connect SLF4J to your logging framework, add a binding JAR in your classpath. If you use a build tool such as Maven or Gradle, this usually involves adding a runtime dependency to your application descriptor (pom.xml or build.gradle). For example, here is a Maven snippet for Logback:

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>...</version>
</dependency>

And the same for Log4J:

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

Check SLF4J’s documentation for examples for other logging frameworks, and for troubleshooting dependency resolution problems.

Each logging framework has its own configuration rules, but all of them provide different levels (DEBUG, INFO, WARN, ERROR…), different loggers or categories (messages from different categories or loggers can be filtered out separately or printed out differently), and different appenders (message receptacles such as the standard console, the error console, a file on disk, a socket…).

Check your logging framework documentation for more information about how to properly configure it. You can also find some configuration examples at the end of this page.

Performance tips:

Use asynchronous appenders; both Log4J and Logback provide asynchronous appenders which reduce the impact of logging in latency-sensitive applications.
While the driver does not provide such capability, it is possible for client applications to hot-reload the log configuration without stopping the application. This usually involves JMX and is available for Logback; Log4J provides a configureAndWatch() method but it is not recommended to use it inside J2EE containers (see FAQ).

Taxonomy of driver logs

The driver has a well-defined use for each log level. As an application developer/administrator, you should be focusing mostly on the ERROR, WARN and INFO levels.

ERROR

Something that renders the driver – or a part of it – completely unusable. An action is required to fix it: bouncing the client, applying a patch, etc.

WARN

Something that the driver can recover from automatically, but indicates a configuration or programming error that should be addressed. For example:

WARN  c.d.o.d.i.core.session.PoolManager - [s0] Detected a keyspace change at runtime (<none> =>
test). This is an anti-pattern that should be avoided in production (see
'request.warn-if-set-keyspace' in the configuration).

WARN  c.d.o.d.i.c.c.CqlPrepareHandlerBase - Re-preparing already prepared query. This is generally
an anti-pattern and will likely affect performance. The cached version of the PreparedStatement
will be returned, which may use different bound statement execution parameters (CL, timeout, etc.)
from the current session.prepare call. Consider preparing the statement only once. Query='...'

INFO

Something that is part of the normal operation of the driver, but might be useful to know for an administrator. For example:

INFO  c.d.o.d.i.c.metadata.MetadataManager - [s0] No contact points provided, defaulting to
/127.0.0.1:9042

INFO  c.d.o.d.internal.core.time.Clock - Using native clock for microsecond precision

INFO  c.d.o.d.i.c.c.t.DefaultDriverConfigLoader - [s0] Detected a configuration change

DEBUG and TRACE

These levels are intended primarily for driver developers; we might ask you to enable them to investigate an issue.

Keep in mind that they are quite verbose, in particular TRACE. It’s a good idea to only enable them on a limited set of categories.

Logging request latencies

The driver provides a built-in component to log the latency and outcome of every application request. See the request tracker page for more details.

Configuration examples

Logback

Here is a sample configuration file for Logback.

It logs driver messages of level INFO and above, and all other libraries at level ERROR only.

The appenders send all messages of level INFO and above to the console, and all messages to a rolling file (with the current configuration, the console and log file have the same contents, but if you were to enable DEBUG logs for a category, those logs would go to the file but not the console).

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

  <!-- log INFO or higher messages to the console -->
  <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%-5p %msg%n</pattern>
    </encoder>
  </appender>

  <!-- log everything to a rolling file -->
  <appender name="file" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>driver.log</file>
    <encoder>
      <pattern>%-5p [%d{ISO8601}] [%t] %F:%L - %msg%n</pattern>
    </encoder>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <!-- daily rollover -->
      <fileNamePattern>driver.%d{yyyy-MM-dd}.log</fileNamePattern>
      <!-- keep 30 days' worth of history -->
      <maxHistory>30</maxHistory>
    </rollingPolicy>
    </appender>

    <!-- use AsyncAppender for lower latencies -->
    <appender name="async" class="ch.qos.logback.classic.AsyncAppender">
      <appender-ref ref="console" />
      <appender-ref ref="file" />
    </appender>

    <root level="ERROR">
      <appender-ref ref="async" />
    </root>
    <logger name="com.datastax.oss.driver" level= "INFO"/>
</configuration>

Log4J

Here is a sample configuration file for Log4J.