[ENHANCEMENT] prometheus: add instant mode to queries

[SoWieMarkus]

Description

This enhancement adds an instant query mode to the Prometheus time series query plugin, allowing individual queries to be executed as instant queries rather than range queries, independent of the panel-level query mode.

Previously, instant queries were only triggered by the panel context's mode field. With this change, a query-level instant flag can be set directly on the PrometheusTimeSeriesQuerySpec, giving users per-query control - similar to how Grafana handles this.

A prior attempt at instant query support (#738) was reverted because it broke the sparkline feature. A follow-up approach (#746) proposed coupling the query mode to the sparkline (instant for the stat value, range for the sparkline), but that approach has a drawback: instant and range queries can e.g. return a different number of time series if a series disappears within the configured time frame, leading to mismatches. This PR sidesteps that problem by attaching the instant flag to the individual query rather than the panel, decoupling it from sparkline behavior entirely. This way, the instant flag gives users explicit, unambiguous control over the query behavior.

Screenshots

Adds an query mode selection to the query:

instant also disables the sparkline:

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.
• Code follows the UI guidelines.

[s3onghyun]

I think your approach is the better one, and it addresses exactly the objection @tgitelman raised on #746.

My PR was constrained by queryOptions returning a single panel-level { mode }: it could only ever pick one mode for the whole panel, so it couldn't give the value an instant query while the sparkline keeps a range query. That's the real fix here, and #746 couldn't express it. Worse, as you and @tgitelman both point out, a single shared range query can be wrong for the value anyway (Loki's split_queries_by_interval, series appearing/disappearing within the window) — so "value correct when sparkline off" was the most #746 could honestly claim, and even that's a narrow slice.

A per-query instant flag on PrometheusTimeSeriesQuerySpec is the right layer: it's explicit, it matches how Grafana does it, and it lets a stat panel run an instant query for the value and a range query for the sparkline as two independent queries. That decouples them properly instead of trying to infer one mode from the spec.

So I'd rather back #752 than push mine. I'll close #746 in favour of it. Two small things from my side that might be worth carrying over:

• The stat panel still needs to choose to issue an instant query for its value once the flag exists — happy to do that follow-up on the StatChart side once [ENHANCEMENT] prometheus: add instant mode to queries #752 lands, reusing the sparkline/calculation reasoning (only last is instant-safe; last-number, aggregations, and the sparkline need range).
• The regression tests I wrote for the sparkline case ([BUGFIX] Statchart: request instant queries for stat panels #738's failure) could move over so that path stays covered.

Nice work — this is the cleaner design.

[celian-garcia]

Cool feature ! Visually I'd vote for a segmented button like Grafana. The advantage is to really know what is the other option.

https://mui.com/material-ui/react-button-group/

[Nexucis]

Thank you for your time working on this topic @SoWieMarkus and @s3onghyun ! It is really cool to see the community working together to reach a consensus and bring a good solution to a broader problem.

regarding the go-sdk and the schema it looks good to me.
Over to the frontend maintainers to finish the review even if the changes look reasonable to me :)

[SoWieMarkus]

@celian-garcia Implemented your feedback and updated the PR description / screenshots.

[Gladorme]

Some thought about the PR, I did not review it for now. But for sure, it will needs option "auto", for setting the value to undefined

instant and range queries can e.g. return a different number of time series if a series disappears within the configured time frame, leading to mismatches

The disappears behavior, should be handled by the panel, to me. But maybe I miss something.
Adding a layer of range/instant in all panels look strange, I wonder if it's really well supported by all panels and explorer.

[s3onghyun]

Thanks @Nexucis 🙌

One concrete data point for @Gladorme's "the disappearing-series behaviour should be handled by the panel" — for StatChart at least, it already is: StatChartPanel maps over result.data.series and renders one stat per series (isMultiSeries), so if instant and range return different series counts it just shows a different number of cards rather than breaking. So the panel tolerating a variable count isn't extra work there; it's the existing behaviour.

I can't speak to whether every panel + the explorer degrade as gracefully — that's the broader question you're raising and it's yours and @SoWieMarkus's call. Just wanted to confirm the StatChart corner, since that's the one I dug into.

On auto: agreed a 3-state (instant / range / auto→undefined) is more expressive than a bool. Whatever shape it lands in, I'm happy to do the StatChart-side follow-up once this merges — issue an instant query for the value when it's safe (only last; last-number, the aggregations, and the sparkline need range) and keep range for the sparkline.

[SoWieMarkus]

Thanks for your feedback @Gladorme.

it will needs option "auto", for setting the value to undefined

Added it to the ButtonGroup and adjusted the code to support undefined as well and use that as the default. I also updated the screenshots in the PR description.

The disappears behavior, should be handled by the panel, to me. But maybe I miss something. Adding a layer of range/instant in all panels look strange, I wonder if it's really well supported by all panels and explorer.

I just started contributing so I am not that familiar with the codebase. I hope I understand you correctly. I do not want to replace the sparkline option - that should definitely remain controllable via panel settings. It is just a "side effect" that the sparkline is disabled when the query is set to instant.

However, since instant and range queries can return different data, I think giving users a per-query override makes sense. Consider a Kubernetes pod lifecycle as an example: a pod can go down and be replaced by a new one spun up by the orchestrator. A range query would return all pods that were alive in the configured time frame. An instant query would only return the pods that are available at the moment.

And this how I stumbled across this issue. I wanted to build a perses dashboard where I am only interested in the state of the pods that are available right now. And I couldn't find a way to build that with perses, since the stat panel is always using range queries. On the other hand, the range query might be what someone else is interested in that example (seeing all pods in the configured time range)

So my thinking is that context.mode (panel) and spec.instant (query) are complementary, not redundant: the panel sets the default mode, and the query can override it per-query (with Auto meaning "respect the panel.") Forcing the query mode at the panel level limits that flexibility (e.g. Grafana also separates instant queries from graph mode in the stat panel).

But ofc there might be / are panels where an instant query would never makes sense.