QueryLogger (Java driver for DataStax Enterprise 1.0.0 API)

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

All Methods Static Methods Instance Methods Abstract Methods Concrete 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)`
`protected int`	`appendParameters(SimpleStatement statement, StringBuilder buffer, int remaining)`
`static QueryLogger.Builder`	`builder()` 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)`
`void`	`onRegister(Cluster cluster)` Gets invoked when the tracker is registered with a cluster, or at cluster startup if the tracker was registered at initialization with `Cluster.register(LatencyTracker)`.
`void`	`onUnregister(Cluster cluster)` Gets invoked when the tracker is unregistered from a cluster, or at cluster shutdown if the tracker was not unregistered.
`protected String`	`parameterValueAsString(ColumnDefinitions.Definition definition, ByteBuffer raw)`
`protected String`	`parameterValueAsString(Object value)`
`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 or a SimpleStatement, then the query parameters (if any) will be logged. For a BoundStatement names and actual values are logged and for a SimpleStatement values are logged in positional order and named values are logged with names and value.
    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 or a SimpleStatement, then the query parameters (if any) will be logged. For a BoundStatement names and actual values are logged and for a SimpleStatement values are logged in positional order and named values are logged with names and value.
    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 complete 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 or a SimpleStatement, then the query parameters (if any) will be logged. For a BoundStatement names and actual values are logged and for a SimpleStatement values are logged in positional order and named values are logged with names and value. 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 volatile 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()
```
    Creates a new QueryLogger.Builder instance.
    This is a convenience method for new QueryLogger.Builder().
    
    Returns:
    
    the new QueryLogger builder.
    
    Throws:
    
    NullPointerException - if cluster is null.
  - onRegister
```
public void onRegister(Cluster cluster)
```
    Description copied from interface: LatencyTracker
    
    Gets invoked when the tracker is registered with a cluster, or at cluster startup if the tracker was registered at initialization with Cluster.register(LatencyTracker).
    
    Specified by:
    
    onRegister in interface LatencyTracker
    
    Parameters:
    
    cluster - the cluster that this tracker is registered with.
  - onUnregister
```
public void onUnregister(Cluster cluster)
```
    Description copied from interface: LatencyTracker
    
    Gets invoked when the tracker is unregistered from a cluster, or at cluster shutdown if the tracker was not unregistered.
    
    Specified by:
    
    onUnregister in interface LatencyTracker
    
    Parameters:
    
    cluster - the cluster that this tracker was registered with.
  - 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)
```
  - appendParameters
```
protected int appendParameters(SimpleStatement statement,
                               StringBuilder buffer,
                               int remaining)
```
  - parameterValueAsString
```
protected String parameterValueAsString(Object value)
```
  - append
```
protected int append(Statement statement,
                     StringBuilder buffer,
                     int remaining)
```
  - append
```
protected int append(CharSequence str,
                     StringBuilder buffer,
                     int remaining)
```

Class QueryLogger

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_SLOW_QUERY_THRESHOLD_MS

DEFAULT_SLOW_QUERY_THRESHOLD_PERCENTILE

DEFAULT_MAX_QUERY_STRING_LENGTH

DEFAULT_MAX_PARAMETER_VALUE_LENGTH

DEFAULT_MAX_LOGGED_PARAMETERS

NORMAL_LOGGER

SLOW_LOGGER

ERROR_LOGGER

cluster

maxQueryStringLength

maxParameterValueLength

maxLoggedParameters

Method Detail

builder

onRegister

onUnregister

getMaxQueryStringLength

setMaxQueryStringLength

getMaxParameterValueLength

setMaxParameterValueLength

getMaxLoggedParameters

setMaxLoggedParameters

update

maybeLogNormalOrSlowQuery

maybeLogNormalQuery

maybeLogErrorQuery

logQuery

statementAsString

countBoundValues

appendParameters

parameterValueAsString

appendParameters

parameterValueAsString

append

append