Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

  • tracing for events and spans. Enable a subscriber that captures the ruprizzle::query, ruprizzle::slow_query, ruprizzle::migrate, ruprizzle::pool, and ruprizzle::connection targets.
  • metrics (behind the metrics feature) for counters, histograms, and gauges. Install a recorder such as metrics-exporter-prometheus or 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

NameTypeLabelsMeaning
ruprizzle_query_totalcounter—Total executed statements.
ruprizzle_query_duration_secondshistogram—Query latency.
ruprizzle_query_errors_totalcounterkindErrors by Error::kind().

Slow queries are emitted as WARN events on the ruprizzle::slow_query tracing target, not as a metric counter.

Pool metrics

NameTypeMeaning
ruprizzle_pool_sizegaugeConnections held by the pool.
ruprizzle_pool_idlegaugeConnections available for checkout.
ruprizzle_pool_in_usegaugeConnections currently checked out.
ruprizzle_pool_waitersgaugeTasks waiting for a connection.

Migration metrics

NameTypeMeaning
ruprizzle_migration_applied_totalcounterMigrations applied.
ruprizzle_migration_duration_secondshistogramPer-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_use near size for a sustained period means the pool is fully utilized.
  • waiters > 0 means requests are queueing. Increase max_connections or reduce query latency.
  • idle near 0 means the pool is sized at the edge. min_connections can smooth out cold-start latency.

What to do when ping fails

pool::ping runs SELECT 1. If it fails:

  1. Check the ruprizzle::connection target for connect and reconnect events. Repeated reconnects mean the network or database process is unstable.
  2. Check ruprizzle::query_errors_total{kind="connection"}. A rising count confirms connection-level failures.
  3. Verify acquire_timeout is not too aggressive for a remote database.
  4. 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_seconds histogram (e.g. p99 above your PoolConfig::slow_query_threshold) or watch WARN events on the ruprizzle::slow_query tracing target.
  • Pool saturation: ruprizzle_pool_waiters > 0 for more than 30 seconds.
  • Migrations stuck: ruprizzle_migration_applied_total not 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.