Logging

Setup

DataStax Java driver uses the popular SLF4J library to emit log messages;
SLF4J has the advantage of providing a logging API that is entirely decoupled from concrete
implementations, letting client applications free to seamlessly connect SLF4J to their preferred logging backend.

The driver itself does not attempt to configure any concrete logging framework.
It is up to client applications using the driver to correctly set up their classpath and
runtime configuration to be able to capture log messages emitted by the driver.
Concretely, client applications need to provide, at runtime, a binding to any logging framework
of their choice that is compatible with SLF4J.

If your application is built with Maven, this usually involves adding one (runtime) dependency to your POM file.
For example, if you intend to use Logback, add the following dependency:

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

Configuration

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 below.

Useful loggers

When debugging the Java driver, the following loggers could be particularly useful
and provide hints about what’s going wrong.

Logging query latencies

The QueryLogger provides clients with the ability to log queries
executed by the driver, and especially, it allows client to track slow
queries, i.e. queries that take longer to complete than a configured
threshold in milliseconds.

To turn on this feature, you first need to instantiate and register a QueryLogger instance:

Note that QueryLogger instances are thread-safe and can be shared cluster-wide.
Besides, you can adjust several parameters such as the maximum query string length to be printed,
the maximum number of parameters to print, etc. Refer to the
QueryLoggerAPI docs for more information.

Secondly, you need to adjust your logging framework to accept log messages from the QueryLogger. The QueryLogger
uses 3 different loggers:

com.datastax.driver.core.QueryLogger.NORMAL : Used to log normal queries, i.e., queries that completed successfully within a configurable threshold in milliseconds.

com.datastax.driver.core.QueryLogger.SLOW : Used to log slow queries, i.e., queries that completed successfully but that took longer than a configurable threshold in milliseconds to complete.

com.datastax.driver.core.QueryLogger.ERROR: Used to log unsuccessful queries, i.e., queries that did not complete normally and threw an exception. Note this this logger will also print the full stack trace of the reported exception.

You need to set the above loggers to DEBUG level to turn them on. E.g. to track queries
that take more than 300 ms to complete, configure your QueryLogger with that threshold (see above),
then set the com.datastax.driver.core.QueryLogger.SLOW logger to DEBUG, e.g. with Log4J:

Be careful when logging large query strings (specially batches) and/or queries with considerable amounts of parameters.
See the QueryLoggerAPI docs for examples of how to truncate the printed message when necessary.

Constant vs Dynamic thresholds

Currently the QueryLogger can be configured to track slow queries using either
a constant threshold in milliseconds (which is the default behavior), or
a dynamic threshold based on per-host latency percentiles, as computed by PerHostPercentileTracker.

Dynamic thresholds are still a beta feature: they haven’t been extensively
tested yet, and the API is still subject to change.

Performance Tips

Use asynchronous appenders; both Log4J
and Logback provide asynchronous appenders
that can significantly boost latencies when writing log messages.

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).

Logback Example

Here is a typical example configuration for Logback. Please adapt it to your specific needs before using it!

It logs messages to the console with levels equal to or higher than INFO, and logs all messages to a rolling file.
By default, only messages with ERROR level or higher are logged.

DataStax, Titan, and TitanDB are registered trademark of DataStax, Inc.
and its subsidiaries in the United States and/or other countries.

Apache Cassandra, Apache, Tomcat, Lucene, Solr, Hadoop, Spark, TinkerPop,
and Cassandra are trademarks of the Apache
Software Foundation or its subsidiaries in Canada, the United States
and/or other countries