Readyset Docs

Every Prometheus metric exported by the QueryPilot Router, its plugins, and the Analytics.

Overview

The Router (binary querypilot) serves Prometheus metrics at its [metrics] bind, default 127.0.0.1:9090, when [metrics] enabled = true. Analytics (binary querypilot-analytics) serves its own metrics at its own [metrics] bind, also defaulting to 127.0.0.1:9090; give the two distinct ports when they share a host. All series names keep the sqp_ prefix.

The Router endpoint exports the core sqp_* series plus the plugin-chain, Guard (sqp_guard_*), and Accelerator (sqp_qp_*) series for whichever plugins are enabled. The Analytics endpoint exports the sqp_duckdb_* and sqp_snapshot_* series.

Series appear on first emission, so a metric is absent until the code path that records it has run at least once. See Operations for alerting guidance.

The protocol label takes the values postgres and mysql. MySQL support is in preview; PostgreSQL is the supported GA v1 path.

Router metrics

Query execution:

Name	Type	Measures	Labels
`sqp_queries_total`	counter	Completed queries	`pool`, `query_type`, `protocol`, `status`
`sqp_query_duration_seconds`	histogram	Query execution latency	`pool`, `query_type`, `protocol`
`sqp_query_rows_returned`	histogram	Rows returned per query	`pool`, `query_type`
`sqp_query_errors_total`	counter	Query errors by classified type	`pool`, `error_type`
`sqp_query_timeout_total`	counter	Queries that hit a per-query or pool deadline	`pool`
`sqp_errors_retryable_total`	counter	Errors classified as transient (deadlock, timeout, lost connection)	`pool`, `error_type`
`sqp_errors_fatal_total`	counter	Errors classified as permanent (syntax, constraint, permission)	`pool`, `error_type`
`sqp_result_bytes_total`	counter	Bytes returned in query results	`pool`, `query_type`

query_type is one of read, write, txn, ddl, admin, session, unknown. status is success or error.

Routing:

Name	Type	Measures	Labels
`sqp_routing_decisions_total`	counter	Routing decisions by kind	`decision_type`, `target_pool`
`sqp_routing_duration_seconds`	histogram	Time to make a routing decision	`decision_type`
`sqp_routing_cache_entries`	gauge	Routing-cache size	none
`sqp_routing_cache_operations_total`	counter	Cache hits, misses, evictions	`operation`
`sqp_routing_rejects_total`	counter	Queries rejected by a rule	`pool`
`sqp_translations_registered`	gauge	Registered translations	none
`sqp_translation_matches_total`	counter	Queries matched by a translation	`target_pool`

decision_type is one of translation, pattern, regex, default, pinned.

Connection pools and backends:

Name	Type	Measures	Labels
`sqp_pool_connections`	gauge	Pooled connections by state (`available`, `in_use`)	`pool`, `state`
`sqp_pool_connections_max`	gauge	Configured connection ceiling	`pool`
`sqp_pool_acquire_total`	counter	Connection acquisitions by outcome (`reused`, `created`, `waited`, `timeout`)	`pool`, `outcome`
`sqp_pool_acquire_duration_seconds`	histogram	Acquire latency	`pool`, `outcome`
`sqp_pool_errors_total`	counter	Pool errors	`pool`, `error_type`
`sqp_pool_queue_depth`	gauge	Requests waiting for a connection	`pool`
`sqp_pool_wait_duration_seconds`	histogram	Time from request to acquisition	`pool`
`sqp_pool_timeouts_total`	counter	Acquire timeouts	`pool`
`sqp_pool_utilization_ratio`	gauge	In-use over max connections	`pool`
`sqp_pool_connection_lifetime_seconds`	histogram	Connection lifetime at release	`pool`
`sqp_backend_health`	gauge	Backend health (1 healthy, 0 unhealthy)	`pool`, `backend`
`sqp_backend_connect_duration_seconds`	histogram	Backend connect time	`pool`, `backend`
`sqp_backend_errors_total`	counter	Backend errors	`pool`, `backend`, `error_type`

Sessions and transactions:

Name	Type	Measures	Labels
`sqp_sessions_active`	gauge	Active client sessions	`protocol`
`sqp_transactions_active`	gauge	Open transactions	`pool`
`sqp_transaction_duration_seconds`	histogram	Transaction duration at completion	`pool`
`sqp_transaction_idle_seconds`	histogram	Idle time between queries inside a transaction	`pool`
`sqp_transaction_abandoned_total`	counter	Clients that disconnected mid-transaction	`pool`
`sqp_session_replay_failures_total`	counter	Session-variable replay failures	`pool`
`sqp_session_auto_rollback_total`	counter	Automatic ROLLBACKs on session close	`pool`
`sqp_session_auto_rollback_failed_total`	counter	Auto-ROLLBACKs that failed on the backend	`pool`
`sqp_auth_failures_total`	counter	Client authentication failures	`protocol`, `reason`

Protocol layer:

Name	Type	Measures
`sqp_postgres_connections_created_total`	counter	PostgreSQL backend connections opened
`sqp_postgres_connections_closed_total`	counter	PostgreSQL backend connections closed
`sqp_postgres_connections_reset_total`	counter	PostgreSQL backend connections reset for reuse
`sqp_postgres_statements_prepared_total`	counter	Statements prepared on PostgreSQL backends
`sqp_postgres_execute_passthrough_total`	counter	Executes forwarded via raw passthrough
`sqp_mysql_connections_created_total`	counter	MySQL backend connections opened
`sqp_mysql_connections_closed_total`	counter	MySQL backend connections closed
`sqp_mysql_connections_reset_total`	counter	MySQL backend connections reset for reuse
`sqp_mysql_connections_recovered_total`	counter	MySQL connections recovered after streaming
`sqp_mysql_statements_prepared_total`	counter	Statements prepared on MySQL backends
`sqp_mysql_streaming_task_panics_total`	counter	MySQL streaming tasks that panicked
`sqp_mysql_streaming_tasks_aborted_total`	counter	MySQL streaming tasks aborted

Plugin chain metrics

Emitted by the Router's plugin chain for any registered plugin.

Name	Type	Measures	Labels
`sqp_plugin_panic_total`	counter	Plugin hooks that panicked (contained; the query proceeds per enforcement mode)	`plugin`
`sqp_plugin_timeout_total`	counter	Plugin hooks that exceeded their time budget	`plugin`

Guard metrics

Emitted when [plugins.guard] is enabled.

Name	Type	Measures	Labels
`sqp_guard_decisions_total`	counter	Decisions by action (`allow`, `block`, `amend`, `reroute`)	`action`, `policy`, `trust_level`
`sqp_guard_decision_duration_seconds`	histogram	Decision-pipeline latency	`action`
`sqp_guard_amendments_total`	counter	Query amendments applied (`add_limit`, `add_timeout`, `force_read_only`)	`type`
`sqp_guard_unanalyzable_total`	counter	Statements Guard could not analyze; the alerting signal for `unanalyzable_action = "log"`	`source`
`sqp_guard_timeouts_total`	counter	Decisions that blew the latency cap and failed open	none
`sqp_guard_panics_total`	counter	Decision-pipeline panics (contained)	none
`sqp_guard_registry_hits_total`	counter	Trusted-query registry hits	none
`sqp_guard_registry_misses_total`	counter	Trusted-query registry misses	none
`sqp_guard_audit_dropped_total`	counter	Audit records dropped because the channel was full or closed	none
`sqp_guard_audit_file_writes_total`	counter	Audit records written by the file sink	none
`sqp_guard_audit_file_write_errors_total`	counter	File-sink write failures (disk full, read-only mount)	none
`sqp_guard_audit_file_flush_errors_total`	counter	File-sink flush failures	none
`sqp_guard_audit_serialize_errors_total`	counter	Audit records that failed to serialize	none
`sqp_guard_audit_sink_panics_total`	counter	Audit-sink panics (record dropped)	none

Accelerator metrics

Emitted when [plugins.accelerator] is enabled. The stalest-gauge alert pattern: watch time() - sqp_qp_last_success_timestamp_seconds; a stalled or repeatedly failing discovery loop stops advancing it while the proxy keeps serving.

Name	Type	Measures	Labels
`sqp_qp_cycles_total`	counter	Completed discovery cycles by result	`result`
`sqp_qp_cycle_duration_seconds`	histogram	Discovery-cycle wall-clock duration	none
`sqp_qp_errors_total`	counter	Cycle-stage errors (fail-open), including `panic`	`stage`
`sqp_qp_last_success_timestamp_seconds`	gauge	Unix time of the last fully successful cycle	none
`sqp_qp_candidates_total`	counter	Caching candidates surfaced by discovery	none
`sqp_qp_rules_added_total`	counter	Routing rules installed by the Accelerator	none
`sqp_qp_rules_enabled_total`	counter	Rules enabled (for example after warmup)	none
`sqp_qp_rules_disabled_total`	counter	Rules disabled (for example on health failure)	none
`sqp_qp_rules_dropped_total`	counter	Rules removed	none
`sqp_qp_support_checks_total`	counter	Readyset support checks by outcome (`supported`, `unsupported`, `pending`, `cached`, `skipped`, `error`)	`status`
`sqp_qp_caches_created_total`	counter	Readyset caches created successfully	none

Analytics metrics

Served from the Analytics's own metrics endpoint.

Queries and connections:

Name	Type	Measures	Labels
`sqp_duckdb_queries_total`	counter	Queries on the PostgreSQL wire endpoint	`query_type`, `status`
`sqp_duckdb_query_duration_seconds`	histogram	Query latency	`query_type`
`sqp_duckdb_query_errors_total`	counter	Query errors	`error_type`
`sqp_duckdb_connections_active`	gauge	Active client connections	none
`sqp_duckdb_connections_total`	counter	Connections accepted since start	none
`sqp_duckdb_reader_queries_total`	counter	Queries dispatched to read-pool connections	`reader`
`sqp_duckdb_reader_errors_total`	counter	Read-pool dispatch errors (`channel_full`, `disconnected`)	`reader`, `error_type`
`sqp_duckdb_reader_pool_live`	gauge	Live readers in the read pool	none
`sqp_duckdb_memory_bytes`	gauge	DuckDB memory usage	none
`sqp_duckdb_database_size_bytes`	gauge	Database file size	none

Replication and snapshots:

Name	Type	Measures	Labels
`sqp_duckdb_replication_lag_seconds`	gauge	CDC replication lag	none
`sqp_duckdb_tables_replicated`	gauge	Tables in the replication filter	none
`sqp_duckdb_snapshot_strategy_info`	gauge	Info gauge (value 1) naming the active snapshot strategy	`strategy`
`sqp_snapshot_rows_total`	counter	Snapshot rows completed per table	`table`, `strategy`
`sqp_snapshot_bytes_total`	counter	Snapshot bytes completed per table	`table`, `strategy`
`sqp_snapshot_rows_estimated_total`	gauge	Estimated total rows for the running snapshot	`table`, `strategy`
`sqp_snapshot_started_at_seconds`	gauge	Unix start time of the running snapshot	`table`, `strategy`
`sqp_snapshot_phase`	gauge	Active snapshot phase (1 for the current phase, 0 otherwise)	`table`, `strategy`, `phase`

Parquet streaming snapshot pipeline (snapshot_strategy = "parquet_streaming"; see advanced snapshot tuning):

Name	Type	Measures	Labels
`sqp_duckdb_parquet_snapshot_counter_mismatch_total`	counter	Read/written/ingested row-counter disagreements at the reconciliation gate	`table`
`sqp_duckdb_parquet_snapshot_writer_panic_total`	counter	Parquet writer panics	`table`
`sqp_duckdb_parquet_snapshot_ingest_failure_total`	counter	Ingest insert failures by bounded reason (`timeout`, `oom`, `schema_mismatch`, `constraint`, `other`)	`table`, `reason`
`sqp_duckdb_parquet_snapshot_swap_failure_total`	counter	Failed staging-to-target swaps	`table`
`sqp_duckdb_parquet_snapshot_swap_duration_seconds`	histogram	Staging-to-target swap duration	`table`
`sqp_duckdb_parquet_snapshot_scratch_pressure_total`	counter	Snapshot aborts due to low scratch space	`table`
`sqp_duckdb_parquet_snapshot_preflight_warn_total`	counter	Scratch pre-flight checks skipped or warned	none
`sqp_duckdb_parquet_snapshot_reconciliation_bypass_total`	counter	Swaps performed with strict reconciliation disabled; alert on any increase	none
`sqp_duckdb_orphan_staging_tables_reaped_total`	counter	Orphan staging tables dropped by the startup reaper	none
`sqp_duckdb_parquet_snapshot_ingest_queue_depth_files`	gauge	Parquet files queued for ingest	`table`
`sqp_duckdb_parquet_snapshot_ingest_queue_depth_bytes`	gauge	Bytes queued for ingest	`table`
`sqp_duckdb_parquet_snapshot_scratch_bytes_used`	gauge	Scratch disk in use by the snapshot	`table`

Metrics