ClickHouse / ClickHouse/clickhouse-connect

Enable passing OTEL trace context to client's query methods

Open
#303 2 comments 1 reaction 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
521
Forks
159
Avg merge
1d 7h
Merged PRs (30d)
46

Description

**Is your feature request related to a problem? Please describe.**

As per the [ClickHouse docs](https://clickhouse.com/docs/en/operations/opentelemetry):

> ClickHouse accepts trace context HTTP headers, as described by the [W3C recommendation](https://www.w3.org/TR/trace-context/).

At the moment, there is no clean way to pass Open Telemetry trace context when calling a client's query methods.
I realize the feature is "experimental", but the format of the header and OTEL itself can be deemed as stable. Therefore it's unlikely to change at the client layer and probably fine to already implement (but of course up to the maintainers to decide).

**Describe the solution you'd like**

I'd like to be able to pass a `trace_context: TraceContext` query arg to each of the query methods, which would set the trace context headers/metadata when making the request to the server.

The `TraceContext` object would contain a subset of the fields from [OTEL's `SpanContext`](https://opentelemetry-python.readthedocs.io/en/latest/api/trace.span.html?highlight=SpanContext#opentelemetry.trace.span.SpanContext) -- only the fields that need to be included in the header.

**Describe alternatives you've considered**

One can implement this functionality by subclassing the client class of course, but it would be nice if it's built-in.

**Additional context**

- ClickHouse OTEL documentation: https://clickhouse.com/docs/en/operations/opentelemetry
- W3C trace context spec: https://www.w3.org/TR/trace-context/
- OTEL python library `SpanContext`: https://opentelemetry-python.readthedocs.io/en/latest/api/trace.span.html?highlight=SpanContext#opentelemetry.trace.span.SpanContext

Contributor guide

Open the contributing guide

Research direction

Start by locating the client's query methods and the request construction they share. Review the ClickHouse OTEL and W3C trace-context references in the issue, then determine how the proposed trace_context argument should reach outgoing requests. Done means query methods can accept the context and send the corresponding trace headers or metadata, with coverage for the new behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend-api-design, observability
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.