Client config reporting — stage 1 (groundwork): SESSION_ID + DRIVER_CONFIG plumbing#967
Open
nikagra wants to merge 1 commit into
Open
Client config reporting — stage 1 (groundwork): SESSION_ID + DRIVER_CONFIG plumbing#967nikagra wants to merge 1 commit into
nikagra wants to merge 1 commit into
Conversation
…plumbing)
Stage 1 of driver configuration reporting: the mechanism to report a client's
effective configuration to ScyllaDB at connection time, so operators can inspect
driver settings (via system.clients.client_options) while investigating incidents.
Gated behind a new option, advanced.client-config-reporting.enabled, which
ships disabled — when off there is zero change on the wire. When enabled:
- SESSION_ID: a dedicated, driver-generated per-session UUID, sent on every
connection (control and pool) so the server can group a session's
connections. Independent of the user-settable CLIENT_ID.
- DRIVER_CONFIG: a compact JSON blob, sent only on the control connection.
Stage 1 emits only {"version":1}; the full configuration report follows in
stage 2.
Both entries are produced by a new DriverConfigReporter, invoked per connection
from ProtocolInitHandler and evaluated fresh (so toggling the flag at runtime
takes effect on new connections). Reporting is fail-safe: any failure while
building the report is swallowed and never breaks connection initialization.
The config option is registered consistently across DefaultDriverOption,
TypedDriverOption, OptionsMap.driverDefaults() and reference.conf.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
📝 WalkthroughWalkthroughAdds the Sequence Diagram(s)sequenceDiagram
participant ControlConnection
participant ProtocolInitHandler
participant DriverConfigReporter
participant ScyllaDB
ControlConnection->>ProtocolInitHandler: initialize channel with reportConfig(true)
ProtocolInitHandler->>DriverConfigReporter: populateStartupOptions(options, true)
DriverConfigReporter-->>ProtocolInitHandler: SESSION_ID and DRIVER_CONFIG
ProtocolInitHandler->>ScyllaDB: send STARTUP options
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 PMD (7.26.0)core/src/main/java/com/datastax/oss/driver/internal/core/channel/ProtocolInitHandler.javaopenjdk version "17.0.19" 2026-04-21 LTS Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java`:
- Around line 1178-1184: Update the enabled-flag documentation in
DefaultDriverOption and the matching reference.conf entry so it states that both
SESSION_ID and DRIVER_CONFIG are emitted only when reporting is enabled, while
preserving their differing connection scopes: SESSION_ID on every connection and
DRIVER_CONFIG on the control connection only.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: a34d18a8-2a95-4e3b-ab1e-3c1e44ca6f84
📒 Files selected for processing (14)
core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.javacore/src/main/java/com/datastax/oss/driver/api/core/config/OptionsMap.javacore/src/main/java/com/datastax/oss/driver/api/core/config/TypedDriverOption.javacore/src/main/java/com/datastax/oss/driver/internal/core/channel/DriverChannelOptions.javacore/src/main/java/com/datastax/oss/driver/internal/core/channel/ProtocolInitHandler.javacore/src/main/java/com/datastax/oss/driver/internal/core/context/DefaultDriverConfigReporter.javacore/src/main/java/com/datastax/oss/driver/internal/core/context/DefaultDriverContext.javacore/src/main/java/com/datastax/oss/driver/internal/core/context/DriverConfigReporter.javacore/src/main/java/com/datastax/oss/driver/internal/core/context/InternalDriverContext.javacore/src/main/java/com/datastax/oss/driver/internal/core/control/ControlConnection.javacore/src/main/resources/reference.confcore/src/test/java/com/datastax/oss/driver/internal/core/channel/ChannelFactoryTestBase.javacore/src/test/java/com/datastax/oss/driver/internal/core/channel/ProtocolInitHandlerTest.javacore/src/test/java/com/datastax/oss/driver/internal/core/context/DefaultDriverConfigReporterTest.java
Comment on lines
+1178
to
+1184
| * Whether the driver reports its effective client configuration to ScyllaDB at connection time. | ||
| * | ||
| * <p>When {@code true}, the driver sends a compact JSON description of its configuration in the | ||
| * CQL {@code STARTUP} options under the {@code DRIVER_CONFIG} key (control connection only); | ||
| * ScyllaDB stores it in {@code system.clients.client_options} so operators can inspect driver | ||
| * settings while investigating incidents. Independently of this flag, a {@code SESSION_ID} | ||
| * startup option is sent on every connection so the server can group a session's connections. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Correct the enabled-flag documentation. SESSION_ID is not independent of this flag: when reporting is disabled, the reporter emits neither startup option.
core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java#L1178-L1184: state that bothSESSION_IDandDRIVER_CONFIGare sent only when enabled, with their differing connection scopes.core/src/main/resources/reference.conf#L1209-L1221: make the same correction in the user-facing reference configuration.
📍 Affects 2 files
core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java#L1178-L1184(this comment)core/src/main/resources/reference.conf#L1209-L1221
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java`
around lines 1178 - 1184, Update the enabled-flag documentation in
DefaultDriverOption and the matching reference.conf entry so it states that both
SESSION_ID and DRIVER_CONFIG are emitted only when reporting is enabled, while
preserving their differing connection scopes: SESSION_ID on every connection and
DRIVER_CONFIG on the control connection only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What ☑️
Stage 1 (groundwork) of driver configuration reporting: the mechanism for the driver to report its effective client configuration to ScyllaDB at connection time, so operators can inspect driver settings (via
system.clients.client_options) while investigating incidents. Follows the cross-driver JSON schema design.This is phase 1 of 2 and is intentionally a draft — it lands the plumbing; the full configuration report (all groups) comes in phase 2.
Behavior 🚸
Gated behind a new option
advanced.client-config-reporting.enabled, which ships disabled — when off there is zero change on the wire. When enabled:SESSION_ID— a dedicated, driver-generated per-session UUID, sent on every connection (control and pool) as aSTARTUPoption, so the server can group all of a session's connections. Independent of the user-settableCLIENT_ID(so it is guaranteed unique per session).DRIVER_CONFIG— a compact JSON blob, sent only on the control connection. Stage 1 emits only{"version":1}; the full report follows in phase 2.Both entries are produced by a new
DriverConfigReporter, invoked per connection fromProtocolInitHandlerand evaluated fresh (so toggling the flag at runtime takes effect on new connections). Reporting is fail-safe: any failure while building the report is swallowed and never breaks connection initialization.Changes ✍️
DefaultDriverOption,TypedDriverOption,OptionsMap.driverDefaults(),reference.conf.DriverConfigReporter/DefaultDriverConfigReporteron the driver context (per-session singleton holding the dedicated session id).DriverChannelOptions.reportConfigflag; hook added inProtocolInitHandler.Testing 🔨
Unit tests 💻
DefaultDriverConfigReporterTest; updatedProtocolInitHandlerTestandChannelFactoryTestBase.TypedDriverOptionTest,MapBasedDriverConfigLoaderTest,TypesafeDriverConfigTest).coreunit test suite green: 3865 tests, 0 failures.Manual tests ✋
Environment: 🌌
CLIENT_CONFIG_REPORTING_ENABLED➡️true127.0.0.1:9042Sample 1: Control connection STARTUP frame
Note
Note both
DRIVER_CONFIGandSESSION_IDare presentSample 2: Connection STARTUP frame
Note
Note just
SESSION_IDis presentSample 3: Control connection STARTUP frame (
CLIENT_CONFIG_REPORTING_ENABLEDisfalse)Note
Note neither
DRIVER_CONFIGnorSESSION_IDis presentFollow-up (phase 2)
STARTUPkeys and has no problematicclient_optionsvalue-length cap.Fixes DRIVER-832
🤖 Generated with Claude Code