questllens-health-check

questllens-health-check

Triage order. Each step is cheap and rules out a class of problem, so run them in sequence rather than jumping to the one that matches your hunch.

1. Ingestion first — it explains most "missing data"

get_ingestion_health is the single highest-value call. One round trip gives you, per table: WAL lag, suspended state, the latest designated-timestamp value, and staleness against wall clock — sorted suspended-first, then by lag.

Read it in this order:

• Suspended tables. A suspended WAL means writes are accepted but never applied. Queries return stale data with no error anywhere. This is the top-priority finding and it is invisible from the query path alone.
• High lag. Apply is behind. Data is arriving but not yet visible. Often transient under load; sustained lag is a real problem.
• Staleness with zero lag. WAL is healthy and caught up, and the newest row is still old — so nothing is writing. The problem is upstream of QuestDB, not inside it.

That last distinction matters more than any other in this skill: lag is a database problem, staleness without lag is a producer problem. Don't report "ingestion is broken" without saying which.

get_wal_status drills into WAL apply state, per-table lag, and sequencer vs writer transaction numbers when you need the detail behind a finding.

2. Is anything actually running

get_running_queries — optionally with min_duration_ms to filter noise. A long-running query can starve apply and make lag look like a data problem.

questllens cannot cancel a query. Report what's running, its duration, and the impact; the operator decides.

3. Storage and layout

• get_storage_summary with top_n — largest tables, native vs parquet. Run this before anyone asks "why is the disk full".
• get_partitions with summary=true — roll-up totals per table; drop summary and use from/to to inspect a suspicious window. Look for: a missing partition (ingestion gap), a partition far larger than its neighbours (backfill or out-of-order write storm), or a partition count that doesn't match the retention the operator expects.
• get_table_params — ttl tells you whether retention is configured at all; o3MaxLag and maxUncommittedRows govern how expensive out-of-order writes are.