Operations guide
This document is for the person running ruprizzle in production: what the
runtime emits, what to watch, and what to do when it misbehaves.
Telemetry
ruprizzle uses two telemetry systems:
tracingfor events and spans. Enable a subscriber that captures theruprizzle::query,ruprizzle::slow_query,ruprizzle::migrate,ruprizzle::pool, andruprizzle::connectiontargets.metrics(behind themetricsfeature) for counters, histograms, and gauges. Install a recorder such asmetrics-exporter-prometheusor an OpenTelemetry adapter.
Both systems deliberately avoid PII. Binds are reported as a count, never as values.
What each span means
ruprizzle::query
DEBUG event emitted after every executed statement.
sql— the SQL shape, with placeholders intact.binds— number of placeholder values.rows/rows_affected— result summary.elapsed_ms— how long the statement took.
Enable this target when debugging latency or when you need a query log for auditing.
ruprizzle::slow_query
WARN event emitted when a query exceeds PoolConfig::slow_query_threshold.
sql— the SQL shape.binds— placeholder count.elapsed_ms— actual duration.
Set the threshold to the 99th percentile of normal queries. A slow query is not an outage by itself, but a sustained spike in these events is a leading indicator of saturation or a missing index.
ruprizzle::migrate
INFO events emitted during migration application.
migration— the migration id.statements— number of statements in the file.elapsed_ms— how long the migration took.
A long elapsed_ms on a migration is expected for backfills. A sudden failure
is a WARN or ERROR with the migration id.
ruprizzle::pool and ruprizzle::connection
INFO/WARN events for connection lifecycle (see W3-04).
connect,disconnect,acquire_timeout,reconnect.
Metrics
Enable the metrics feature and install a recorder.
Query metrics
| Name | Type | Labels | Meaning |
|---|---|---|---|
ruprizzle_query_total | counter | — | Total executed statements. |
ruprizzle_query_duration_seconds | histogram | — | Query latency. |
ruprizzle_query_errors_total | counter | kind | Errors by Error::kind(). |
Slow queries are emitted as WARN events on the ruprizzle::slow_query tracing
target, not as a metric counter.
Pool metrics
| Name | Type | Meaning |
|---|---|---|
ruprizzle_pool_size | gauge | Connections held by the pool. |
ruprizzle_pool_idle | gauge | Connections available for checkout. |
ruprizzle_pool_in_use | gauge | Connections currently checked out. |
ruprizzle_pool_waiters | gauge | Tasks waiting for a connection. |
Migration metrics
| Name | Type | Meaning |
|---|---|---|
ruprizzle_migration_applied_total | counter | Migrations applied. |
ruprizzle_migration_duration_seconds | histogram | Per-migration duration. |
How to read PoolStats
#![allow(unused)] fn main() { use ruprizzle::pool; let stats = pool::report_metrics(&pool); println!("size={} idle={} in_use={} waiters={}", stats.size, stats.idle, stats.in_use, stats.waiters); }
report_metrics also emits the current values to the metrics recorder.
Interpretation:
in_usenearsizefor a sustained period means the pool is fully utilized.waiters> 0 means requests are queueing. Increasemax_connectionsor reduce query latency.idlenear 0 means the pool is sized at the edge.min_connectionscan smooth out cold-start latency.
What to do when ping fails
pool::ping runs SELECT 1. If it fails:
- Check the
ruprizzle::connectiontarget forconnectandreconnectevents. Repeated reconnects mean the network or database process is unstable. - Check
ruprizzle::query_errors_total{kind="connection"}. A rising count confirms connection-level failures. - Verify
acquire_timeoutis not too aggressive for a remote database. - If using
sqlite-rusqlite, ensure the database file is on a local volume with write access.
Read-replica routing
RoutedPool sends reads to replicas and keeps writes and transactions on the primary.
A raw statement goes to a replica only if it starts with SELECT, WITH, VALUES,
TABLE or SHOW and contains none of INSERT, UPDATE, DELETE, MERGE, INTO,
RETURNING, LOCK, SHARE, NEXTVAL or SETVAL as a word; anything else, such as
SELECT … FOR UPDATE or INSERT … RETURNING, runs on the primary.
use ruprizzle::{connect, LoadBalancing, RoutedPool};
let routed = RoutedPool::builder(connect(&primary_url).await?)
.add_replica(connect(&replica_a_url).await?)
.add_replica(connect(&replica_b_url).await?)
.load_balancing(LoadBalancing::LeastConnections)
.fallback_to_primary(true)
.build();
let read_pool = routed.select_replica(); // a healthy replica, or the primary
let tx = routed.begin().await?; // always the primary
LoadBalancing is RoundRobin (the default), LeastConnections, or Random. A
replica is only ever chosen while it is marked healthy, and check_health() pings
every replica and updates those flags. Nothing pings in the background unless you
ask: let _checks = routed.spawn_health_checks(Duration::from_secs(5)); (since 1.6)
runs check_health() on that interval until the returned handle is dropped, or
call check_health() from your own supervisor. With fallback_to_primary(true), a
read is served by the primary when no replica is healthy rather than failing; set it
to false when moving read load onto the primary is worse than an error: reads through
the router then fail with a fallback_to_primary error. LeastConnections counts the
reads in flight through the router on each replica (a stream counts until dropped);
Random draws uniformly per call.
Query result cache
QueryCache is the trait; InMemoryCache is the bundled implementation, bounded by a
maximum entry count and invalidated either by TTL or by tag.
use ruprizzle::{InMemoryCache, QueryCache};
use std::time::Duration;
let cache = InMemoryCache::new(10_000);
cache.set("users:active", encoded, Some(Duration::from_secs(30)), &["users"]);
let hit = cache.get("users:active"); // None once the TTL has passed
cache.invalidate_tag("users"); // drop everything tagged `users`
Tags are the invalidation unit: tag each cached result with the tables it was read
from, and invalidate that tag on every write to those tables. Entries expire lazily on
read; prune_expired() reclaims memory eagerly if you would rather not wait for the
next lookup. Implement QueryCache yourself to put the same interface in front of
Redis or any other shared store — nothing in the trait assumes a single process.
The cache is manual. Query execution never reads or writes it: you call get
before a query and set after it, and ruprizzle_cache_hits_total /
ruprizzle_cache_misses_total are not emitted. SelectQuery::cache, cache_key and
cache_tag exist in the 1.5 API but do nothing, and are deprecated since
1.5.2. So are SelectQuery::use_primary and use_replica. To choose a pool, build
the query on RoutedPool::primary(), on the RoutedPool itself, or on
select_replica().
Alerts
Suggested thresholds for a health dashboard:
- Error rate:
rate(ruprizzle_query_errors_total[5m]) > 0.01/sec. - Slow query rate: use the
ruprizzle_query_duration_secondshistogram (e.g. p99 above yourPoolConfig::slow_query_threshold) or watchWARNevents on theruprizzle::slow_querytracing target. - Pool saturation:
ruprizzle_pool_waiters > 0for more than 30 seconds. - Migrations stuck:
ruprizzle_migration_applied_totalnot increasing while a deployment is expected.
Example Prometheus scrape
[dependencies]
ruprizzle = { version = "1.5", features = ["metrics"] }
metrics-exporter-prometheus = "0.15"
#![allow(unused)] fn main() { use metrics_exporter_prometheus::PrometheusBuilder; PrometheusBuilder::new() .install_recorder() .expect("failed to install Prometheus recorder"); }
The recorder will expose ruprizzle_* metrics on the configured endpoint. Point
Grafana at the same endpoint for the dashboard above.