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