Observability¶

DBWarden provides Prometheus metrics and structured JSON logging for monitoring and debugging.

Prometheus metrics¶

Installation¶

Install the optional metrics dependency:

uv add "dbwarden[metrics]"

This installs prometheus-client which is required for metric collection and exposition.

Enabling metrics¶

Set the DBWARDEN_METRICS environment variable to true:

export DBWARDEN_METRICS=true

When enabled, DBWarden instruments the migrate and seed apply commands with Prometheus metric recording. When disabled (or when prometheus_client is not installed), all metric functions are safe no-ops.

Available metrics¶

FastAPI metrics endpoint¶

The MetricsRouter exposes a GET /metrics endpoint in Prometheus text format:

from fastapi import FastAPI
from dbwarden.fastapi import MetricsRouter

app = FastAPI()
app.include_router(MetricsRouter(), prefix="/metrics")

The endpoint returns:

# HELP dbwarden_pending_migrations Number of pending migrations
# TYPE dbwarden_pending_migrations gauge
dbwarden_pending_migrations{database="primary"} 0
# HELP dbwarden_schema_version Current schema version
# TYPE dbwarden_schema_version gauge
dbwarden_schema_version{database="primary"} 5.0

Only active when prometheus_client is installed and DBWARDEN_METRICS=true is set. Returns 404 when disabled.

MetricsMiddleware¶

The MetricsMiddleware is an ASGI middleware that refreshes pending-migration gauges on each HTTP request:

from fastapi import FastAPI
from dbwarden.fastapi import MetricsMiddleware, MetricsRouter

app = FastAPI()
app.add_middleware(MetricsMiddleware)
app.include_router(MetricsRouter(), prefix="/metrics")

The middleware also records HTTP request duration via the migration duration histogram.

JSON logging¶

DBWarden supports structured JSON logging for integration with log aggregation systems (ELK, Loki, Datadog, etc.).

Enabling JSON logging¶

Set the DBWARDEN_LOG_JSON environment variable to true:

export DBWARDEN_LOG_JSON=true

When enabled, all DBWarden log output uses newline-delimited JSON format:

{"timestamp": "2025-06-01T10:00:00.123456", "level": "INFO", "logger": "dbwarden", "message": "Applying migration 0003", "db_name": "primary", "db_type": "postgresql"}
{"timestamp": "2025-06-01T10:00:01.234567", "level": "INFO", "logger": "dbwarden", "message": "Migration 0003 applied successfully", "db_name": "primary", "db_type": "postgresql"}

JSON log fields¶

Environment variables reference¶

See also: Cookbook: Observability