Documentation
¶
Overview ¶
Package chtrace makes a ClickHouse connection's statements OpenTelemetry spans, the way dbtrace does for Postgres.
A ClickHouse read is usually the slow part of the request that runs it, and without a span it is invisible: a trace shows the handler taking ten seconds and children covering fifteen milliseconds, and nothing says the time went to ClickHouse, which statement it was, or why it ended. Wrap the connection once, where it is opened, and every Query, QueryRow, Select and Exec on it is a CLIENT span carrying:
- db.system.name / db.system "clickhouse", db.operation.name, db.collection.name, and db.query.summary ("SELECT t_org.otel_logs"), which is also the span name;
- db.query.text, the statement with every literal replaced by ?, read by ClickHouse's lexical rules (dbtrace.ClickHouse.Sanitize: a backslash escapes inside every quoted string). Bound parameters are never recorded;
- db.clickhouse.query_id, the id the statement runs under, so the span joins system.query_log (`WHERE query_id = '…'`) for the server's side: its read rows, memory, exception and profile events;
- db.clickhouse.read_rows / read_bytes, what the server reported reading (progress packets), and db.response.returned_rows;
- on failure: the error recorded as an exception event, the span status Error with the message, error.type (the ClickHouse exception name such as TIMEOUT_EXCEEDED, or context_canceled / context_deadline_exceeded — also when the driver reports the statement's expired context as an i/o timeout or a broken connection), and db.response.status_code (the ClickHouse exception code).
A Query span lasts until its rows are closed: streaming the result is part of the statement's cost. A QueryRow span lasts until the row is scanned (Scan or ScanStruct), and records a scan's failure.
Like dbtrace, a span is only opened under an existing span, so a statement with no span in its context (a startup migration) stays out of the traces.
The wrapper sets the statement's query id, progress and profile-info callbacks and its OpenTelemetry span context through clickhouse.Context. A caller that sets its own query id or callbacks on the same context has them replaced; settings and parameters are preserved.
Index ¶
- Constants
- func Describe(query string) (summary string, attrs []attribute.KeyValue)
- func ErrorType(err error) string
- func ErrorTypeContext(ctx context.Context, err error) string
- func RecordError(span trace.Span, err error)
- func RecordErrorContext(ctx context.Context, span trace.Span, err error)
- func Wrap(conn driver.Conn) driver.Conn
Constants ¶
const ( AttrQueryID = "db.clickhouse.query_id" AttrReadRows = "db.clickhouse.read_rows" AttrReadBytes = "db.clickhouse.read_bytes" )
Attribute keys this package sets beyond the OpenTelemetry semantic conventions' db.* set.
const System = "clickhouse"
System is the db.system.name every span carries.
Variables ¶
This section is empty.
Functions ¶
func Describe ¶
Describe is what a statement's span says about it: its summary (the span name: "SELECT t_org.otel_logs") and the db.* attributes, the statement text sanitized. An `EXECUTE AS <user>` prefix is not the operation: the summary is the statement it runs.
func ErrorType ¶
ErrorType is err's low-cardinality class for error.type: context_canceled, context_deadline_exceeded, the ClickHouse exception name (TIMEOUT_EXCEEDED, QUOTA_EXCEEDED, ...), timeout (a network timeout), or _OTHER. It knows only err; ErrorTypeContext also reads the statement's context.
func ErrorTypeContext ¶ added in v1.0.7
ErrorTypeContext is ErrorType for a statement that ran under ctx: an error that does not itself say why the statement ended is the context's verdict when ctx was canceled or its deadline has passed.
func RecordError ¶
RecordError marks span failed by err: the exception event, status Error with the message, error.type, and the ClickHouse code when there is one. It knows only err; RecordErrorContext also reads the statement's context, which is what says a statement the driver failed opaquely ran out of time.
func RecordErrorContext ¶ added in v1.0.7
RecordErrorContext is RecordError for a statement that ran under ctx. When ctx, not err, is what explains the failure — the driver returned an i/o timeout or a broken connection because ctx's deadline passed — error.type names the context's verdict and the status message carries it after err's.
Types ¶
This section is empty.
Source Files