The only tool you need to know what is happening and how to fix it.
Fast by-id lookups (always pass the timestamp)
The by-id detail commands (exceptions occurrence, endpoints show, tasks show, ai-traces show, sessions show, traces show) require the record's timestamp (--recorded-at, or --started-at for sessions). Telemetry tables are partitioned by day: with the timestamp the lookup is bounded to a small window and ClickHouse prunes to a few partitions; without it the server scans every partition (slow cold load). The flag is mandatory for exactly this reason, so never omit it. It can be approximate (within ±24h), and you can recover or estimate it when it isn't handed to you; see "When you don't have the timestamp" below.
Where the timestamp comes from, in order of preference:
- A dashboard URL: the
?t=<iso>param is the record'srecordedAt; URL-decode it and pass it verbatim. (Sessions have not; use the session start,from=, or a linked occurrence'srecordedAt.) - A list/group you already fetched: every
exceptions showoccurrence carriesrecordedAt. Capture the id and itsrecordedAttogether, then drill in. - A notification: see below.
Query order when you hold an id: resolve its recordedAt first (URL, group, or notification), then call the by-id command with it.
When you don't have the timestamp
The flag is required, so you must supply something, but it can be approximate. The lookup window is ±24h around what you pass (±48h for traces show), and if the record isn't in that window the server falls back to an unbounded scan. So a timestamp within a day of the truth stays fast; a wrong guess still returns the right record, just slower. Resolve it in this order:
- Recover it from an API. For an occurrence whose hash you know (e.g.
/issues/<hash>/<occurrenceId>pasted without?t=), runtraceway exceptions show <hash>and read that occurrence'srecordedAt. The hash endpoint needs no timestamp. A group'sfirstSeen/lastSeenfromexceptions listbound when its occurrences happened (lastSeen≈ the most recent one). - Estimate from context. A notification's send time, the issue's
firstSeen/lastSeen, or the URL'spreset/fromwindow all put you inside ±24h. That is good enough for a fast lookup. - Ask the user. If nothing pins it down (e.g. a bare occurrence/endpoint id with no hash, no time, and no list to recover from), ask roughly when it happened ("around when did this fire? within a day is enough") and pass that. Don't invent a placeholder like "now" when the issue is old; that defeats the pruning and can miss the ±24h window entirely.