Readyset Docs

Monitor the slowest queries on a database target, in real time or from historical statistics.

rdst top is a Unix-top-style view of the queries running against a database. It has two modes:

Real-time monitoring (default): samples active queries every few seconds, groups identical query shapes together, and tracks how long each has been running.
Historical (--historical): reads cumulative stats from pg_stat_statements (Postgres) or performance_schema (MySQL) for a lifetime-of-the-database view.

Every query top surfaces is saved to the query registry so you can hand its hash to rdst analyze, rdst cache add, or rdst query run.

Common usage

# Watch live activity
rdst top --target prod-orders

# Capture a 30-second window, then exit (great for CI)
rdst top --target prod-orders --duration 30

# Cumulative view from pg_stat_statements or performance_schema
rdst top --target prod-orders --historical

# JSON output for scripting
rdst top --target prod-orders --duration 10 --json

What the output looks like

rdst top  —  target: prod-orders  (PostgreSQL 15.4)
Sampling every 2s.  Press 'i' to analyze a query, 'q' to quit.

  #   Hash          Calls    Avg time   Max time   Current   Query
  1   a1b2c3d4e5f6  4,812    53.4 ms    412.1 ms   2 active  SELECT * FROM orders WHERE customer_id = $1 ORDER ...
  2   f6e5d4c3b2a1  1,204    139.6 ms   988.2 ms   1 active  SELECT o.*, c.name FROM orders o JOIN customers ...
  3   9a8b7c6d5e4f  51,003   1.6 ms     48.0 ms    0 active  SELECT 1 FROM session_cache WHERE token = $1
  4   4d3c2b1a0f9e  892      74.1 ms    201.8 ms   0 active  UPDATE inventory SET quantity = quantity - $1 ...

The Hash column is your handle for follow-up commands:

rdst analyze --hash a1b2c3d4e5f6 --target prod-orders

Flags reference

Flag	What it does
`--target <name>`	Which configured target to read from
`--duration <seconds>`	Run for a fixed window and exit (non-interactive)
`--historical`	Use cumulative stats instead of sampling live activity
`--source {auto,pg_stat,activity,slowlog,digest,rds,pmm}`	Override the data source (see below)
`--sort {freq,total_time,avg_time,load}`	Change the ordering
`--limit <N>`	Cap the number of rows printed
`--filter <regex>`	Only show queries matching a regex
`--watch`	Continuously refresh (default in TTY mode)
`--interactive`	Pick a query inline and drop into `rdst analyze`
`--json`	Machine-readable output
`--no-color`	Disable ANSI color formatting

Data sources

--source tells RDST where to read query data from. auto picks a sensible default per database type:

Source	What it reads
`pg_stat` (default for `--historical`)	`pg_stat_statements` cumulative stats
`activity`	`pg_stat_activity` live connections
`rds`	Performance Insights via AWS API (RDS targets)

Source	What it reads
`digest` (default for `--historical`)	`performance_schema.events_statements_summary_by_digest`
`slowlog`	`mysql.slow_log` table (requires setup, see below)
`activity`	`SHOW PROCESSLIST`
`pmm`	Percona Monitoring & Management, if configured

Enabling MySQL slow log

The slowlog source requires MySQL's slow query log with TABLE output:

-- Self-hosted MySQL
SET GLOBAL slow_query_log    = 'ON';
SET GLOBAL long_query_time   = 1;
SET GLOBAL log_output        = 'TABLE';

For RDS or Aurora, modify the parameter group (slow_query_log=1, log_output=TABLE). No restart is required.

Interactive mode

In a TTY, top accepts single-keypress commands:

Key	Action
`<digit>`	Save that query to the registry (row number from the display)
`z` then `<digit>`	Hand that query to `rdst analyze`
`a`	Save every query currently on screen to the registry
`q` or Ctrl+C	Quit

--duration <seconds> forces snapshot mode regardless of TTY. This is the right flag for CI, cron jobs, or anything that needs a predictable exit. Use --sort and --filter on the command line to change ordering and filtering instead of keybinds.

rdst top