Expand description
Database client spans and metrics, following the OpenTelemetry semantic conventions for databases. Part of oxtel.
With the rusqlite feature, one line instruments a SQLite connection:
let conn = rusqlite::Connection::open("app.db").unwrap();
oxtel_sql::rusqlite::instrument(&conn);With the postgres feature, one line wraps a tokio-postgres client where
the connection is made, and with deadpool-postgres, a pool (see
oxtel_sql::postgres):
let client = oxtel_sql::postgres::Client::new(client, &config);Every statement they run then gets:
- a client span, named by its query summary (
SELECT users,INSERT orders SELECT carts), withdb.system.name,db.query.summaryanddb.query.text, plusdb.namespaceand the server for PostgreSQL; db.client.operation.duration, through themetricsfacade, by system and query summary;- for PostgreSQL, when it fails, the error’s SQLSTATE as
db.response.status_codeanderror.type, on both.
db.query.text is the statement with every literal replaced by ? and
comments removed, so values never reach telemetry; turn it off with
record_query_text. As the conventions say for raw SQL, the operation
and table names aren’t taken from the text into db.operation.name and
db.collection.name: the summary carries them.
Spans are recorded with tracing and metrics with metrics, so they go
wherever the program sends them: with oxtel::init(), to OTLP or
Prometheus. The spans’ target is oxtel_sql, so RUST_LOG=…,oxtel_sql=off
turns them off.
For sqlx, wrap the pool with the sqlx-0.8 or sqlx-0.9 feature:
oxtel_sql::sqlx::v0_9::Pool::new(pool). oxtel::init() also makes the
same spans and metric from sqlx’s own query events, with no code change,
but without failures or which database a query went to; the
oxtel_sql::sqlx module compares the two.
summarize and sanitize are available on their own, for
instrumenting a database client this crate doesn’t cover.
Modules§
- postgres
- PostgreSQL through tokio-postgres, and deadpool-postgres pools.
- rusqlite
- rusqlite: a span and
db.client.operation.durationfor every statement a connection runs. - sqlx
- sqlx 0.8 and 0.9, by wrapping the pool:
v0_8with thesqlx-0.8feature,v0_9withsqlx-0.9.
Functions§
- describe_
metrics - Describe the metrics this crate records (their units and descriptions)
to the current
metricsrecorder. The instrumentation entry points call it, so it only matters for a recorder installed after them. - record_
query_ text - Record
db.query.texton spans: the statement’s text with every literal replaced by?. Default: true, as the conventions advise for text without values. It applies to the whole process. - records_
query_ text - Whether
db.query.textis recorded; seerecord_query_text. For instrumentation outside this crate that follows the same setting. - sanitize
sqlwith every literal replaced by?, comments removed and runs of space made one, as the database conventions ask before recordingdb.query.text. Placeholders stay, and anINlist of literals collapses toIN (?).- summarize
- A low-cardinality summary of
sqlfordb.query.summaryand the span name, as the database conventions describe it: each operation and the tables it names, in the order they appear, as written, such asSELECT usersorINSERT shipping_details SELECT orders.Nonewhensqlnames no operation this recognizes.