com.datastax.driver.core

Interface DriverConfigReporter

All Known Implementing Classes:

DefaultDriverConfigReporter

@Beta
public interface DriverConfigReporter

Builds the DRIVER_CONFIG payload that the control connection sends in its CQL STARTUP options, so ScyllaDB can store it in system.clients.client_options and operators can inspect a client's effective driver settings while investigating incidents.

Only the control connection carries the blob; pooled connections are correlated back to it via the SESSION_ID startup option, which Connection sends on every connection independently of this reporter and of Cluster.Builder.withDriverConfigReporting(boolean).

system.clients.client_options is per node: only the node holding the control connection stores DRIVER_CONFIG; other nodes only see SESSION_ID-bearing pooled- connection rows. Consumers must query and aggregate across all nodes to see the full picture.

Method Summary

Modifier and Type	Method and Description
String	buildReport() Builds the configuration report, or returns null if it could not be built (in which case no DRIVER_CONFIG option is sent).

Method Detail

buildReport

String buildReport()

Builds the configuration report, or returns null if it could not be built (in which case no DRIVER_CONFIG option is sent).

Called once per control connection, from its STARTUP frame assembly, and not cached: the report describes the objects in force at the handshake that sends it, rather than the configuration the Cluster was constructed from. Implementations must therefore tolerate being called on a Netty event loop, and repeatedly over a cluster's lifetime.

Implementations must not throw: a failure to build the report must be swallowed (and logged) rather than propagated, so that a diagnostic aid can never break cluster initialization. For the same reason they must bound the report's size and return null rather than an oversized one: STARTUP option values carry an unchecked 16-bit length prefix, so a value over 65535 encoded bytes corrupts the frame instead of merely being useless. The built-in reporter caps the report at 32KiB of UTF-8, the limit the other ScyllaDB drivers apply.

An implementation that cannot even be loaded is handled one level up rather than here: DefaultDriverConfigReporter needs Jackson, and on a classpath without it the failure is a LinkageError raised while initializing the class, which no method of this interface could catch. Connection.Factory.buildDriverConfigReport contains that and reports nothing, so the connection is still established.

Returns:

the report to send under the DRIVER_CONFIG startup option, or null to send nothing.