public abstract class QueryLogger extends Object implements LatencyTracker
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:
NORMAL_LOGGER
: used to log normal queries, i.e., queries that completed
successfully within a configurable threshold in milliseconds.
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.
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:
ERROR_LOGGER
;
SLOW_LOGGER
;
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 QueryLogger.Builder.withConstantThreshold(long)
constant threshold} in milliseconds (which is the default
behavior), or using a dynamic
threshold
based on latency percentiles.
This class is thread-safe.
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.
|
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.
|
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(BuiltStatement 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.
|
public static final long DEFAULT_SLOW_QUERY_THRESHOLD_MS
public static final double DEFAULT_SLOW_QUERY_THRESHOLD_PERCENTILE
public static final int DEFAULT_MAX_QUERY_STRING_LENGTH
public static final int DEFAULT_MAX_PARAMETER_VALUE_LENGTH
public static final int DEFAULT_MAX_LOGGED_PARAMETERS
public static final org.slf4j.Logger NORMAL_LOGGER
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
.
public static final org.slf4j.Logger SLOW_LOGGER
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
.
public static final org.slf4j.Logger ERROR_LOGGER
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
.
protected volatile Cluster cluster
protected volatile int maxQueryStringLength
protected volatile int maxParameterValueLength
protected volatile int maxLoggedParameters
public static QueryLogger.Builder builder()
QueryLogger.Builder
instance.
This is a convenience method for new QueryLogger.Builder()
.
NullPointerException
- if cluster
is null
.public void onRegister(Cluster cluster)
LatencyTracker
Cluster.register(LatencyTracker)
.onRegister
in interface LatencyTracker
cluster
- the cluster that this tracker is registered with.public void onUnregister(Cluster cluster)
LatencyTracker
onUnregister
in interface LatencyTracker
cluster
- the cluster that this tracker was registered with.public int getMaxQueryStringLength()
DEFAULT_MAX_QUERY_STRING_LENGTH
.public void setMaxQueryStringLength(int maxQueryStringLength)
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).IllegalArgumentException
- if maxQueryStringLength <= 0 && maxQueryStringLength !=
-1
.public int getMaxParameterValueLength()
DEFAULT_MAX_PARAMETER_VALUE_LENGTH
.public void setMaxParameterValueLength(int maxParameterValueLength)
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).IllegalArgumentException
- if maxParameterValueLength <= 0 &&
maxParameterValueLength != -1
.public int getMaxLoggedParameters()
DEFAULT_MAX_LOGGED_PARAMETERS
.public void setMaxLoggedParameters(int maxLoggedParameters)
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).IllegalArgumentException
- if maxLoggedParameters <= 0 && maxLoggedParameters !=
-1
.public void update(Host host, Statement statement, Exception exception, long newLatencyNanos)
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.
update
in interface LatencyTracker
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).protected abstract void maybeLogNormalOrSlowQuery(Host host, Statement statement, long latencyMs)
protected void maybeLogNormalQuery(Host host, Statement statement, long latencyMs)
protected void maybeLogErrorQuery(Host host, Statement statement, Exception exception, long latencyMs)
protected void logQuery(Statement statement, Exception exception, org.slf4j.Logger logger, String message)
protected int countBoundValues(BatchStatement bs)
protected int appendParameters(BoundStatement statement, StringBuilder buffer, int remaining)
protected String parameterValueAsString(ColumnDefinitions.Definition definition, ByteBuffer raw)
protected int appendParameters(SimpleStatement statement, StringBuilder buffer, int remaining)
protected int appendParameters(BuiltStatement statement, StringBuilder buffer, int remaining)
protected int append(Statement statement, StringBuilder buffer, int remaining)
protected int append(CharSequence str, StringBuilder buffer, int remaining)
Copyright © 2012–2023. All rights reserved.