Readyset Docs

rdst top

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. For persistent history and Inbox findings, use RDST Agent.

The CLI modes are:

  • 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 totals since statistics were last reset.

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 'z' then a row number to analyze, '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

FlagWhat it does
--target <name>Which configured target to read from
--duration <seconds>Run for a fixed window and exit (non-interactive)
--historicalUse 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
--watchContinuously refresh (default in TTY mode)
--interactivePick a query inline and drop into rdst analyze
--jsonMachine-readable output
--no-colorDisable ANSI color formatting

Data sources

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

SourceWhat it reads
pg_stat (default for --historical)pg_stat_statements cumulative stats
activitypg_stat_activity live connections
rdsPerformance Insights via AWS API (RDS targets)
SourceWhat it reads
digest (default for --historical)performance_schema.events_statements_summary_by_digest
slowlogmysql.slow_log table (requires setup, see below)
activitySHOW PROCESSLIST
pmmPercona 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:

KeyAction
<digit>Save that query to the registry (row number from the display)
z then <digit>Hand that query to rdst analyze
aSave every query currently on screen to the registry
q or Ctrl+CQuit

--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.

See also