Skip to main content

Crate oxtel_sql

Crate oxtel_sql 

Source
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), with db.system.name, db.query.summary and db.query.text, plus db.namespace and the server for PostgreSQL;
  • db.client.operation.duration, through the metrics facade, by system and query summary;
  • for PostgreSQL, when it fails, the error’s SQLSTATE as db.response.status_code and error.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.duration for every statement a connection runs.
sqlx
sqlx 0.8 and 0.9, by wrapping the pool: v0_8 with the sqlx-0.8 feature, v0_9 with sqlx-0.9.

Functions§

describe_metrics
Describe the metrics this crate records (their units and descriptions) to the current metrics recorder. The instrumentation entry points call it, so it only matters for a recorder installed after them.
record_query_text
Record db.query.text on 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.text is recorded; see record_query_text. For instrumentation outside this crate that follows the same setting.
sanitize
sql with every literal replaced by ?, comments removed and runs of space made one, as the database conventions ask before recording db.query.text. Placeholders stay, and an IN list of literals collapses to IN (?).
summarize
A low-cardinality summary of sql for db.query.summary and the span name, as the database conventions describe it: each operation and the tables it names, in the order they appear, as written, such as SELECT users or INSERT shipping_details SELECT orders. None when sql names no operation this recognizes.