Observability

Structured logging, the pluggable metrics protocol (Prometheus or OpenTelemetry Metrics adapters), and OpenTelemetry tracing (§25). All three are graceful no-ops by default.

Tracer

Tracer(
    *,
    enabled: bool,
    tracer_provider: Any = None,
    schema_url: str | None = None,
    attributes: Mapping[str, Any] | None = None,
)

Wraps an OpenTelemetry tracer; every method is a no-op if OTel isn't installed/enabled.

tracer_provider/schema_url/attributes are the same parameters opentelemetry.trace.get_tracer itself accepts — pass a tracer_provider to bind to a specific (non-global) provider, e.g. per-tenant tracing or test isolation.

A no-op tracer if enabled is False or opentelemetry-api isn't installed.

enabled property

enabled: bool

Whether this tracer actually records spans (False = full no-op).

span

span(
    name: str,
    *,
    db_system: str = "postgresql",
    operation_type: str | None = None,
    query_name: str | None = None,
    database: str | None = None,
    shard: str | None = None,
    role: str | None = None,
) -> Iterator[SpanHandle]

A database operation span (§25.2). Attributes never include SQL text or params.

SpanHandle

SpanHandle(span: Any)

Thin wrapper so callers can set attributes without checking None/OTel presence.

Wrap span, or None for a no-op handle.

set_attribute

set_attribute(key: str, value: Any) -> None

Set a span attribute; a no-op if this handle wraps no real span.

make_tracer

make_tracer(
    enabled: bool,
    *,
    tracer_provider: Any = None,
    schema_url: str | None = None,
    attributes: Mapping[str, Any] | None = None,
) -> Tracer

Build a :class:Tracer (see its docstring for tracer_provider/schema_url/ attributes).

MetricsSink

Bases: Protocol

Minimal metrics surface dbkit emits to.

incr

incr(
    name: str,
    value: float = 1.0,
    labels: Labels | None = None,
) -> None

Increment a counter metric by value.

observe

observe(
    name: str, value: float, labels: Labels | None = None
) -> None

Record one observation of a histogram/summary metric.

gauge

gauge(
    name: str, value: float, labels: Labels | None = None
) -> None

Set a gauge metric to its current value.

NoopMetrics

Default sink — does nothing, allocates nothing meaningful on the hot path.

incr

incr(
    name: str,
    value: float = 1.0,
    labels: Labels | None = None,
) -> None

Does nothing.

observe

observe(
    name: str, value: float, labels: Labels | None = None
) -> None

Does nothing.

gauge

gauge(
    name: str, value: float, labels: Labels | None = None
) -> None

Does nothing.

try_prometheus_sink

try_prometheus_sink(
    namespace: str = "dbkit",
) -> MetricsSink

Construct a Prometheus-backed sink, or raise if prometheus_client is missing.

try_otel_metrics_sink

try_otel_metrics_sink(
    meter_name: str = "dbkit", meter_provider: Any = None
) -> MetricsSink

Construct an OpenTelemetry Metrics-backed sink, or raise if opentelemetry-api is missing. An alternative to :func:try_prometheus_sink — pick one per deployment.

log_event

log_event(
    level: int,
    event: str,
    *,
    query_name: str | None = None,
    database: str | None = None,
    shard: str | None = None,
    role: str | None = None,
    duration_ms: float | None = None,
    pool_wait_ms: float | None = None,
    rows: int | None = None,
    retry_attempt: int | None = None,
    error_code: str | None = None,
    **extra: Any,
) -> None

Emit one structured lifecycle event (§25.3).

slow_query_warning

slow_query_warning(
    *,
    query_name: str,
    duration_ms: float,
    threshold_ms: float,
    database: str | None = None,
    pool_wait_ms: float | None = None,
    rows: int | None = None,
) -> None

Emit a database.query.slow warning (caller decides whether the threshold was hit).

long_transaction_warning

long_transaction_warning(
    *,
    duration_ms: float,
    threshold_ms: float,
    database: str | None = None,
    role: str | None = None,
    outcome: str | None = None,
) -> None

Warn when an explicit transaction was held open longer than the configured threshold — the transaction analog of the pool's long-connection-hold warning (§10.5, §16).