[ENHANCEMENT] Prometheus: explain why $__rate_interval cannot be used as Min Step

[rajusem]

Description

Closes perses/perses#2025.

Using $__rate_interval as the Min Step of a Prometheus query breaks the panel with Invalid duration string '$__rate_interval', which names neither the field nor the reason. It is easy to end up there: the field accepts variables, and the Grafana migration copies the interval of a query into minStep (migrate.cue).

$__interval, $__interval_ms and $__rate_interval cannot work there: they are computed from the step, whose lower bound is the Min Step, and they are replaced only in the PromQL query. As proposed in the issue, this PR keeps the Perses behaviour and only makes the error explicit. (With $__rate_interval as Min step, Grafana uses the rate interval itself as the step, see query.go. Perses has no such setting, so the message suggests the default of the field or a fixed duration.)

A new internal helper, getMinStepSeconds (min-step.ts, not exported from the package), resolves the dashboard variables and then checks the resolved value, which also removes the as DurationString cast and its TODO. Each case below used to fail with Invalid duration string '<resolved value>':

Min Step	Error now
$__rate_interval or ${__rate_interval}	'$__rate_interval' cannot be used as Min Step, because its value depends on the Min Step. Leave Min Step empty to use the scrape interval of the datasource, or set a duration such as 30s.
$__interval, $__interval_ms	the same, with '$__interval' or '$__interval_ms'
$res, where res = $__rate_interval	Min Step '$res' resolves to '$__rate_interval', which cannot be used as Min Step, because … (same end)
30 s	Invalid Min Step '30 s': expected a duration such as 30s or 5m
$res, where res = abc	Invalid Min Step '$res' (resolved to 'abc'): expected a duration such as 30s or 5m

• Only the error text changes: the same values are accepted or rejected as before, with the same step. An empty Min Step, or a variable with an empty value, still falls back to the scrape interval of the datasource, and 0s still sets no lower bound.
• Range and instant queries get the same message.
• The helper has its own file so that get-time-series-data.ts, which [FEATURE] Prometheus: rangeQueryBatch client and getTimeSeriesDataBatch #839 also edits, only changes its imports and one statement.
• docs/prometheus/README.md now says that these built-in variables cannot be used to set the Min Step.

Tests:

• min-step.test.ts: each message, durations (0s gives 0), variables, the empty-variable fallback, and a check that every built-in variable of the datasource gets the message, so that a new one cannot be forgotten.
• plugin.test.ts, through getTimeSeriesData: the message for range and instant queries, with no request sent, and the unchanged step for a variable, an empty variable and 0s in Min Step.

Root npm run lint, format:check, type-check and test pass with Node 24.19.0, with no new lint warnings, and make checklicense passes.

Notes for reviewers:

• In Instant mode the Min Step field is disabled, so switch to Range or Auto to clear it. Making it editable is left for a follow-up.
• There is no editor change: the panel preview shows the new message after Run Query.
• Not changed here: dependsOn ignores the variables used only in Min Step, so changing one of them does not re-run the query (nor does the query wait for it to load), and a Min Step error can stay on screen after the variable has changed. The fix changes the query keys, so it is left for a separate PR.
• [FEATURE] Prometheus: rangeQueryBatch client and getTimeSeriesDataBatch #839 adds a batch path in get-time-series-data.ts that parses the Min Step with getDurationStringSeconds(replaceVariables(…) as DurationString). This PR removes the getDurationStringSeconds and DurationString imports from that file (replaceVariables stays), so after a rebase that path should call getMinStepSeconds(s.minStep, context.variableState) ?? datasourceScrapeInterval.

Screenshots

No screenshot: only the error text changes (see the table above).

Checklist

• Pull request has a descriptive title and context useful to a reviewer.
• Pull request title follows the [<catalog_entry>] <commit message> naming convention using one of the
  following catalog_entry values: FEATURE, ENHANCEMENT, BUGFIX, BREAKINGCHANGE, DOC,IGNORE.
• All commits have DCO signoffs.

UI Changes

• Changes that impact the UI include screenshots and/or screencasts of the relevant changes. (No screenshot: the only UI change is the error text, shown as text above.)
• Code follows the UI guidelines. (N/A)

[Copilot]

Copilot review overview

🟢 Approval recommended

The focused change has regression coverage for improved errors and preserved behavior, with no unresolved findings.

Review effort: Balanced
Findings: None

What changed in this PR

Improves Prometheus Min Step errors without changing accepted values, fallback behavior, or query steps.

Changes:

• Adds an internal helper explaining unsupported built-in variables and invalid durations.
• Adds regression coverage for errors, variable resolution, and step behavior.
• Documents why step-dependent variables cannot set Min Step.

File	Description
prometheus/​src/​plugins/​prometheus-time-series-query/​plugin.test.ts	Tests query errors and unchanged step behavior.
prometheus/​src/​plugins/​prometheus-time-series-query/​min-step.ts	Resolves Min Step variables and provides explicit errors.
prometheus/​src/​plugins/​prometheus-time-series-query/​min-step.test.ts	Tests validation messages and duration handling.
prometheus/​src/​plugins/​prometheus-time-series-query/​get-time-series-data.ts	Uses the new Min Step helper.
docs/​prometheus/​README.md	Explains the built-in variable restriction.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[AntoineThebaud]

Thanks for addressing this long-standing issue 🙏