Skip to content

add query settings injection with OpenTelemetry trace context#102

Open
ancieg wants to merge 2 commits into
Protryon:masterfrom
ancieg:master
Open

add query settings injection with OpenTelemetry trace context#102
ancieg wants to merge 2 commits into
Protryon:masterfrom
ancieg:master

Conversation

@ancieg

@ancieg ancieg commented Jun 11, 2026

Copy link
Copy Markdown

This change lets the driver pass ClickHouse query settings through the client.

That's needed for distributed tracing. If you set a W3C traceparent value in ClientOptions.settings (key opentelemetry_traceparent), the driver copies it into the native protocol OpenTelemetry field so ClickHouse will nest query spans under the existing trace.

  • ClientOptions: new settings field (IndexMap<String, String>), defaults to empty so ClientOptions::default() behaviour is unchanged.
  • query_raw and insert_native_raw: new third argument query_settings: Option<IndexMap<String, String>> for per-query overrides (pass None to keep defaults).
  • No other APIs (query, execute, insert_native, etc.) are changed.

Example:

let mut opts = ClientOptions::default();
opts.settings.insert(
    "opentelemetry_traceparent".into(),
    "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01".into(),
);
opts.settings.insert("log_comment".into(), "my-service".into());
let client = Client::connect("127.0.0.1:9000", opts).await?;

// These pick up defaults automatically
client.execute("SELECT 1").await?;
client.query_collect::<MyRow>("SELECT * FROM t").await?;

// Per-query override
let overrides: IndexMap<String, String> =
    [("log_comment".into(), "adhoc".into())].into_iter().collect();
client.query_raw("SELECT 2", Some(overrides)).await?;

ancieg added 2 commits June 11, 2026 21:46
Enable passing ClickHouse query-level settings through the native protocol
QUERY packet, filling the longstanding TODO in the protocol layer.  The
driver now mirrors clickhouse-driver (Python): arbitrary key-value settings
are serialized in wire format and automatically merged from per-connection
defaults (ClientOptions::settings) with optional per-query overrides on
query_raw and insert_native_raw.

OpenTelemetry distributed tracing is wired in as a first-class concern —
the driver parses W3C traceparent headers from settings and populates the
native protocol's OpenTelemetry field in ClientInfo, so queries appear in
ClickHouse traces with correct trace/span IDs without any extra plumbing on
the caller's side.

Existing public API surface (query, execute, insert_native, etc.) continues
to work unchanged, picking up default settings automatically.
…ction

Covers default settings propagation, per-query overrides, and
insert+readback round-trip.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant