Instant vs Range queries for single-value Stat panels

Answer the question first

For a Stat panel that shows the most recent metric value, use an Instant query when you only need the raw latest sample. If the panel must display a calculation over a recent window (e.g., average, max, sum of the last 5 minutes), you must use a Range query wrapped in an appropriate aggregation function such as avg_over_time(), max_over_time(), or sum_over_time(). An Instant query cannot perform window‑based calculations.

Confirmed facts

• An Instant query returns the single most recent sample available at query time, minimizing payload and browser work.
• A Range query returns all samples within the selected time interval; the panel then applies a reduction (e.g., 'Last', 'Max') or you explicitly apply an aggregation function in the query.
• Stat panels display an instant value by default; to show a range‑based result you must add an aggregation function.
• If the metric’s scrape interval is longer than the chosen range window, the Range query may return no data, so knowing the scrape interval is essential.

Steps for this case

1. Determine the required output: raw latest value → Instant query; window‑based calculation → Range query with aggregation.
2. For an Instant query, simply enter the metric expression (e.g., http_requests_total{job="api"}) without any wrapping function.
3. For a window‑based calculation, wrap the metric in an over‑time function matching the desired reduction, e.g.:

   avg_over_time(http_requests_total{job="api"}[5m])

4. Check performance impact: if the metric scrape interval is short (e.g., 15 s) and you choose a large window (e.g., 1 h), the Range query will transfer many points (≈240 samples per series). In such high‑density cases consider:
   • Shortening the window.
   • Using a recording rule or downsampled metric.
   • Staying with an Instant query if the raw latest value suffices.
5. If you are unsure whether the scrape interval supports your chosen window, ask for that detail; it changes the recommendation because a window shorter than the interval yields no data.

When a Range query becomes less performant

A Range query with a reduction is less performant than an Instant query when:

• The metric has a high sample frequency (short scrape interval) relative to the selected window, causing many samples to be fetched and processed.
• The window is large (e.g., several hours) on a high‑cardinality metric, increasing both query load and browser memory usage.
• You do not need the aggregated value; the extra work provides no benefit.

In those scenarios, prefer an Instant query (or a pre‑aggregated recording rule) to keep latency low and resource usage minimal.