Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu
Scylla Java Driver Manual Core driver Logging

Logging¶

Quick overview¶

  • based on SLF4J.

  • config file examples for Logback and Log4J.

If you’re looking for information about the request logger, see the request tracker page.


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.

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.

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

<log4j:configuration>

  <!-- log INFO or higher messages to the console -->
  <appender name="console" class="org.apache.log4j.ConsoleAppender">
    <param name="threshold" value="INFO"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%-5p %m%n"/>
    </layout>
  </appender>
  
  <!-- log everything to a rolling file -->
  <appender name="file" class="org.apache.log4j.RollingFileAppender">
    <param name="file" value="driver.log"/>
    <param name="append" value="false"/>
    <param name="maxFileSize" value="1GB"/>
    <param name="maxBackupIndex" value="10"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%-5p [%d{ISO8601}] [%t] %F:%L - %m%n"/>
    </layout>
  </appender>
  
  <!-- use AsyncAppender for lower latencies -->
  <appender name="async" class="org.apache.log4j.AsyncAppender">
    <param name="BufferSize" value="500"/>
    <appender-ref ref="file"/>
    <appender-ref ref="console"/>
  </appender>
  
  <root>
    <priority value="ERROR"/>
    <appender-ref ref="async"/>
  </root>
  <logger name="com.datastax.oss.driver">
    <level value="INFO"/>
  </logger>
  
</log4j:configuration>
PREVIOUS
Load balancing
NEXT
Metadata
  • 4.13.0.x
    • 4.13.0.x
    • 4.12.0.x
    • 4.11.1.x
    • 4.10.0.x
    • 4.7.2.x
    • 3.11.2.x
    • 3.11.0.x
    • 3.10.2.x
    • 3.7.2.x
  • Java Driver for Scylla and Apache Cassandra®
  • API Documentation
  • Manual
    • API conventions
    • Case sensitivity
    • Core driver
      • Address resolution
      • Asynchronous programming
      • Authentication
      • Bill of Materials (BOM)
      • Compression
      • Configuration
        • Reference configuration
      • Control connection
      • Custom codecs
      • Detachable types
      • Using the driver in GraalVM native images
      • Query idempotence
      • Integration
      • Load balancing
      • Logging
      • Metadata
        • Node metadata
        • Schema metadata
        • Token metadata
      • Metrics
      • Native protocol
      • Non-blocking programming
      • Paging
      • Performance
      • Connection pooling
      • Query timestamps
      • Reactive Style Programming
      • Reconnection
      • Request tracker
      • Retries
      • Using the shaded JAR
      • Speculative query execution
      • SSL
      • Statements
        • Batch statements
        • Per-query keyspace
        • Prepared statements
        • Simple statements
      • Temporal types
      • Request throttling
      • Query tracing
      • Tuples
      • User-defined types
    • Developer docs
      • Administrative tasks
      • Common infrastructure
        • Concurrency
        • Driver context
        • Event bus
      • Native protocol layer
      • Netty pipeline
      • Request execution
    • Mapper
      • Integration
        • Kotlin
        • Lombok
        • Java 14 Records
        • Scala
      • DAOs
        • Custom result types
        • Delete methods
        • GetEntity methods
        • Increment methods
        • Insert methods
        • Null saving strategy
        • Query methods
        • Query provider methods
        • Select methods
        • SetEntity methods
        • Statement attributes
        • Update methods
      • Entities
      • Mapper interface
    • OSGi
    • Query builder
      • Conditions
      • DELETE
      • Idempotence in the query builder
      • INSERT
      • Relations
      • Schema builder
        • Aggregate
        • Function
        • Index
        • Keyspace
        • Materialized View
        • Table
        • Type
      • SELECT
      • Terms
      • TRUNCATE
      • UPDATE
  • Upgrade guide
  • Frequently asked questions
  • Changelog
  • Create an issue
  • Edit this page

On this page

  • Logging
    • Quick overview
    • Setup
    • Taxonomy of driver logs
      • ERROR
      • WARN
      • INFO
      • DEBUG and TRACE
    • Configuration examples
      • Logback
      • Log4J
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© 2022, ScyllaDB. All rights reserved.
Last updated on 25 May 2022.
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2