Readyset QueryPilotReference
Metrics
Every Prometheus metric exported by the QueryPilot Router and its plugins.
Overview
The Router (binary querypilot) serves Prometheus metrics at its [metrics] bind, default 127.0.0.1:9090, when [metrics] enabled = true. All series names keep the sqp_ prefix.
The endpoint exports the core sqp_* series plus the plugin-chain, Guard (sqp_guard_*), and Accelerator (sqp_qp_*) series for whichever plugins are enabled.
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 |