com.datastax.driver.core

Class QueryLogger

java.lang.Object

com.datastax.driver.core.QueryLogger

All Implemented Interfaces:

LatencyTracker

Direct Known Subclasses:

QueryLogger.ConstantThresholdQueryLogger, QueryLogger.DynamicThresholdQueryLogger

public abstract class QueryLogger
extends Object
implements LatencyTracker

A configurable LatencyTracker that logs all executed statements.

Typically, client applications would instantiate one single query logger (using its QueryLogger.Builder), configure it and register it on the relevant Cluster instance, e.g.:

 Cluster cluster = ...
 QueryLogger queryLogger = QueryLogger.builder(cluster)
     .withConstantThreshold(...)
     .withMaxQueryStringLength(...)
     .build();
 cluster.register(queryLogger);
 

Refer to the QueryLogger.Builder documentation for more information on configuration settings for the query logger.

Once registered, the query logger will log every RegularStatement, BoundStatement or BatchStatement executed by the driver; note that it will never log other types of statement, null statements nor any special statement used internally by the driver.

There is one log for each request to a Cassandra node; because the driver sometimes retries the same statement on multiple nodes, a single statement execution (for example, a single call to Session.execute(Statement)) can produce multiple logs on different nodes.

For more flexibility, the query logger uses 3 different Logger instances:

1. NORMAL_LOGGER: used to log normal queries, i.e., queries that completed successfully within a configurable threshold in milliseconds.
2. SLOW_LOGGER: used to log slow queries, i.e., queries that completed successfully but that took longer than a configurable threshold in milliseconds to complete.
3. ERROR_LOGGER: used to log unsuccessful queries, i.e., queries that did not completed normally and threw an exception. Note this this logger will also print the full stack trace of the reported exception.

The appropriate logger is chosen according to the following algorithm:

1. if an exception has been thrown: use ERROR_LOGGER;
2. otherwise, if the reported latency is greater than the configured threshold in milliseconds: use SLOW_LOGGER;
3. otherwise, use NORMAL_LOGGER.

All loggers are activated by setting their levels to DEBUG or TRACE (including ERROR_LOGGER). If the level is set to TRACE and the statement being logged is a BoundStatement, then the query parameters (if any) will be logged as well (names and actual values).

Constant thresholds vs. Dynamic thresholds

Currently the QueryLogger can track slow queries in two different ways: using a constant threshold in milliseconds (which is the default behavior), or using a dynamic threshold based on per-host percentiles computed by PerHostPercentileTracker.

Note that the dynamic threshold version is currently provided as a beta preview: it hasn't been extensively tested yet, and the API is still subject to change. To use it, you must first obtain and register an instance of PerHostPercentileTracker, then create your QueryLogger as follows:

 Cluster cluster = ...
 // create an instance of PerHostPercentileTracker and register it
 PerHostPercentileTracker tracker = ...;
 cluster.register(tracker);
 // create an instance of QueryLogger and register it
 QueryLogger queryLogger = QueryLogger.builder(cluster)
     .withDynamicThreshold(tracker, ...)
     .withMaxQueryStringLength(...)
     .build();
 cluster.register(queryLogger);
 

This class is thread-safe.

Since:

2.0.10

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	QueryLogger.Builder Helper class to build QueryLogger instances with a fluent API.
static class	QueryLogger.ConstantThresholdQueryLogger A QueryLogger that uses a constant threshold in milliseconds to track slow queries.
static class	QueryLogger.DynamicThresholdQueryLogger A QueryLogger that uses a dynamic threshold in milliseconds to track slow queries.

Field Summary

Fields

Modifier and Type	Field and Description
protected Cluster	cluster
static int	DEFAULT_MAX_LOGGED_PARAMETERS The default maximum number of query parameters that can be logged by the driver.
static int	DEFAULT_MAX_PARAMETER_VALUE_LENGTH The default maximum length of a query parameter value that can be logged verbatim by the driver.
static int	DEFAULT_MAX_QUERY_STRING_LENGTH The default maximum length of a CQL query string that can be logged verbatim by the driver.
static long	DEFAULT_SLOW_QUERY_THRESHOLD_MS The default latency threshold in milliseconds beyond which queries are considered 'slow' and logged as such by the driver.
static double	DEFAULT_SLOW_QUERY_THRESHOLD_PERCENTILE The default latency percentile beyond which queries are considered 'slow' and logged as such by the driver.
static org.slf4j.Logger	ERROR_LOGGER The logger used to log unsuccessful queries, i.e., queries that did not completed normally and threw an exception.
protected int	maxLoggedParameters
protected int	maxParameterValueLength
protected int	maxQueryStringLength
static org.slf4j.Logger	NORMAL_LOGGER The logger used to log normal queries, i.e., queries that completed successfully within a configurable threshold in milliseconds.
static org.slf4j.Logger	SLOW_LOGGER The logger used to log slow queries, i.e., queries that completed successfully but whose execution time exceeded a configurable threshold in milliseconds.

Method Summary

Methods

Modifier and Type	Method and Description
protected int	append(CharSequence str, StringBuilder buffer, int remaining)
protected int	append(Statement statement, StringBuilder buffer, int remaining)
protected int	appendParameters(BoundStatement statement, StringBuilder buffer, int remaining)
static QueryLogger.Builder	builder(Cluster cluster) Creates a new QueryLogger.Builder instance.
protected int	countBoundValues(BatchStatement bs)
int	getMaxLoggedParameters() Return the maximum number of query parameters that can be logged by the driver.
int	getMaxParameterValueLength() Return the maximum length of a query parameter value that can be logged verbatim by the driver.
int	getMaxQueryStringLength() Return the maximum length of a CQL query string that can be logged verbatim by the driver.
protected void	logQuery(Statement statement, Exception exception, org.slf4j.Logger logger, String message)
protected void	maybeLogErrorQuery(Host host, Statement statement, Exception exception, long latencyMs)
protected abstract void	maybeLogNormalOrSlowQuery(Host host, Statement statement, long latencyMs)
protected void	maybeLogNormalQuery(Host host, Statement statement, long latencyMs)
protected String	parameterValueAsString(ColumnDefinitions.Definition definition, ByteBuffer raw)
void	setMaxLoggedParameters(int maxLoggedParameters) Set the maximum number of query parameters that can be logged by the driver.
void	setMaxParameterValueLength(int maxParameterValueLength) Set the maximum length of a query parameter value that can be logged verbatim by the driver.
void	setMaxQueryStringLength(int maxQueryStringLength) Set the maximum length of a CQL query string that can be logged verbatim by the driver.
protected String	statementAsString(Statement statement)
void	update(Host host, Statement statement, Exception exception, long newLatencyNanos) A method that is called after each request to a Cassandra node with the duration of that operation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_SLOW_QUERY_THRESHOLD_MS

public static final long DEFAULT_SLOW_QUERY_THRESHOLD_MS

The default latency threshold in milliseconds beyond which queries are considered 'slow' and logged as such by the driver.

See Also:

Constant Field Values

DEFAULT_SLOW_QUERY_THRESHOLD_PERCENTILE

public static final double DEFAULT_SLOW_QUERY_THRESHOLD_PERCENTILE

The default latency percentile beyond which queries are considered 'slow' and logged as such by the driver.

See Also:

Constant Field Values

DEFAULT_MAX_QUERY_STRING_LENGTH

public static final int DEFAULT_MAX_QUERY_STRING_LENGTH

The default maximum length of a CQL query string that can be logged verbatim by the driver. Query strings longer than this value will be truncated when logged.

See Also:

Constant Field Values

DEFAULT_MAX_PARAMETER_VALUE_LENGTH

public static final int DEFAULT_MAX_PARAMETER_VALUE_LENGTH

The default maximum length of a query parameter value that can be logged verbatim by the driver. Parameter values longer than this value will be truncated when logged.

See Also:

Constant Field Values

DEFAULT_MAX_LOGGED_PARAMETERS

public static final int DEFAULT_MAX_LOGGED_PARAMETERS

The default maximum number of query parameters that can be logged by the driver. Queries with a number of parameters higher than this value will not have all their parameters logged.

See Also:

Constant Field Values

NORMAL_LOGGER

public static final org.slf4j.Logger NORMAL_LOGGER

The logger used to log normal queries, i.e., queries that completed successfully within a configurable threshold in milliseconds.

This logger is activated by setting its level to DEBUG or TRACE. Additionally, if the level is set to TRACE and the statement being logged is a BoundStatement, then the query parameters (if any) will be logged as well (names and actual values).

The name of this logger is com.datastax.driver.core.QueryLogger.NORMAL.

SLOW_LOGGER

public static final org.slf4j.Logger SLOW_LOGGER

The logger used to log slow queries, i.e., queries that completed successfully but whose execution time exceeded a configurable threshold in milliseconds.

This logger is activated by setting its level to DEBUG or TRACE. Additionally, if the level is set to TRACE and the statement being logged is a BoundStatement, then the query parameters (if any) will be logged as well (names and actual values).

The name of this logger is com.datastax.driver.core.QueryLogger.SLOW.

ERROR_LOGGER

public static final org.slf4j.Logger ERROR_LOGGER

The logger used to log unsuccessful queries, i.e., queries that did not completed normally and threw an exception.

This logger is activated by setting its level to DEBUG or TRACE. Additionally, if the level is set to TRACE and the statement being logged is a BoundStatement, then the query parameters (if any) will be logged as well (names and actual values). Note this this logger will also print the full stack trace of the reported exception.

The name of this logger is com.datastax.driver.core.QueryLogger.ERROR.

cluster

protected final Cluster cluster

maxQueryStringLength

protected volatile int maxQueryStringLength

maxParameterValueLength

protected volatile int maxParameterValueLength

maxLoggedParameters

protected volatile int maxLoggedParameters

Method Detail

builder

public static QueryLogger.Builder builder(Cluster cluster)

Creates a new QueryLogger.Builder instance.

This is a convenience method for new QueryLogger.Builder().

Parameters:

cluster - the Cluster this QueryLogger will be attached to.

Returns:

the new QueryLogger builder.

Throws:

NullPointerException - if cluster is null.

getMaxQueryStringLength

public int getMaxQueryStringLength()

Return the maximum length of a CQL query string that can be logged verbatim by the driver. Query strings longer than this value will be truncated when logged. The default value is DEFAULT_MAX_QUERY_STRING_LENGTH.

Returns:

The maximum length of a CQL query string that can be logged verbatim by the driver.

setMaxQueryStringLength

public void setMaxQueryStringLength(int maxQueryStringLength)

Set the maximum length of a CQL query string that can be logged verbatim by the driver. Query strings longer than this value will be truncated when logged.

Parameters:

maxQueryStringLength - The maximum length of a CQL query string that can be logged verbatim by the driver. It must be strictly positive or -1, in which case the query is never truncated (use with care).

Throws:

IllegalArgumentException - if maxQueryStringLength <= 0 && maxQueryStringLength != -1.

getMaxParameterValueLength

public int getMaxParameterValueLength()

Return the maximum length of a query parameter value that can be logged verbatim by the driver. Parameter values longer than this value will be truncated when logged. The default value is DEFAULT_MAX_PARAMETER_VALUE_LENGTH.

Returns:

The maximum length of a query parameter value that can be logged verbatim by the driver.

setMaxParameterValueLength

public void setMaxParameterValueLength(int maxParameterValueLength)

Set the maximum length of a query parameter value that can be logged verbatim by the driver. Parameter values longer than this value will be truncated when logged.

Parameters:

maxParameterValueLength - The maximum length of a query parameter value that can be logged verbatim by the driver. It must be strictly positive or -1, in which case the parameter value is never truncated (use with care).

Throws:

IllegalArgumentException - if maxParameterValueLength <= 0 && maxParameterValueLength != -1.

getMaxLoggedParameters

public int getMaxLoggedParameters()

Return the maximum number of query parameters that can be logged by the driver. Queries with a number of parameters higher than this value will not have all their parameters logged. The default value is DEFAULT_MAX_LOGGED_PARAMETERS.

Returns:

The maximum number of query parameters that can be logged by the driver.

setMaxLoggedParameters

public void setMaxLoggedParameters(int maxLoggedParameters)

Set the maximum number of query parameters that can be logged by the driver. Queries with a number of parameters higher than this value will not have all their parameters logged.

Parameters:

maxLoggedParameters - the maximum number of query parameters that can be logged by the driver. It must be strictly positive or -1, in which case all parameters will be logged, regardless of their number (use with care).

Throws:

IllegalArgumentException - if maxLoggedParameters <= 0 && maxLoggedParameters != -1.

update

public void update(Host host,
          Statement statement,
          Exception exception,
          long newLatencyNanos)

A method that is called after each request to a Cassandra node with the duration of that operation.

Note that there is no guarantee that this method won't be called concurrently by multiple threads, so implementations should synchronize internally if need be.

Specified by:

update in interface LatencyTracker

Parameters:

host - The Cassandra host on which a request has been performed. This parameter is never null.

statement - The Statement that has been executed. This parameter is never null.

exception - An Exception thrown when receiving the response, or null if the response was successful.

newLatencyNanos - the latency in nanoseconds of the operation. This latency corresponds to the time elapsed between when the query was sent to host and when the response was received by the driver (or the operation timed out, in which newLatencyNanos will approximately be the timeout value).

maybeLogNormalOrSlowQuery

protected abstract void maybeLogNormalOrSlowQuery(Host host,
                             Statement statement,
                             long latencyMs)

maybeLogNormalQuery

protected void maybeLogNormalQuery(Host host,
                       Statement statement,
                       long latencyMs)

maybeLogErrorQuery

protected void maybeLogErrorQuery(Host host,
                      Statement statement,
                      Exception exception,
                      long latencyMs)

logQuery

protected void logQuery(Statement statement,
            Exception exception,
            org.slf4j.Logger logger,
            String message)

statementAsString

protected String statementAsString(Statement statement)

countBoundValues

protected int countBoundValues(BatchStatement bs)

appendParameters

protected int appendParameters(BoundStatement statement,
                   StringBuilder buffer,
                   int remaining)

parameterValueAsString

protected String parameterValueAsString(ColumnDefinitions.Definition definition,
                            ByteBuffer raw)

append

protected int append(Statement statement,
         StringBuilder buffer,
         int remaining)

append

protected int append(CharSequence str,
         StringBuilder buffer,
         int remaining)