Rounding timestamps of subqueries

[Brian Candler]

Something that's not clear from the documentation of subquery is how the time is handled.

For example, take foo[5d:1d]. Are the queries done at

- now

- now - 1 day

- now - 2 day ... etc

Or are the query times quantized to utime 1d multiples, e.g.

- midnight just gone

- midnight yesterday

- midnight the day before ... etc

I've been doing some testing with prometheus-2.53.5. Today is 2nd November.

max_over_time(vector(time())[5d:1d])  # 1762041600 = 2025-11-02 00:00:00 +0000

min_over_time(vector(time())[5d:1d])  # 1761696000 = 2025-10-29 00:00:00 +0000

max_over_time(vector(time())[1d:1d])  # 1762041600

min_over_time(vector(time())[1d:1d])  # 1762041600

The latter seems particularly useful, as it gives a way to say "give me the value of this metric as it was midnight (UTC) just gone", which is something I've been trying to do.

My question: is this behaviour intentional, and can be depended on going forward? (e.g. are their unit tests which guarantee it?)

Alternatively, is there a better way to get the value of a metric at the start of a particular time interval?

The above approach works OK for me in the UK, where UTC 00:00 is either midnight or one hour later. But it won't work for "start of the month", and for "start of the week" it gives you a Thursday.

min_over_time(vector(time())[1w:1w])  # 2025-10-30 00:00:00 +0000

Cheers,

Brian.

[Bjoern Rabenstein]

On 02.11.25 09:05, 'Brian Candler' via Prometheus Users wrote:
> Something that's not clear from the documentation of subquery

> <https://prometheus.io/docs/prometheus/latest/querying/basics/#subquery> is

> how the time is handled.
>
> For example, take foo[5d:1d]. Are the queries done at
> - now
> - now - 1 day
> - now - 2 day ... etc
>
> Or are the query times quantized to utime 1d multiples, e.g.
> - midnight just gone
> - midnight yesterday
> - midnight the day before ... etc
>
> I've been doing some testing with prometheus-2.53.5. Today is 2nd November.
>
> max_over_time(vector(time())[5d:1d]) # 1762041600 = 2025-11-02 00:00:00
> +0000
> min_over_time(vector(time())[5d:1d]) # 1761696000 = 2025-10-29 00:00:00
> +0000
>
> max_over_time(vector(time())[1d:1d]) # 1762041600
> min_over_time(vector(time())[1d:1d]) # 1762041600
>
> The latter seems particularly useful, as it gives a way to say "give me the
> value of this metric as it was midnight (UTC) just gone", which is
> something I've been trying to do.
>
> My question: is this behaviour intentional, and can be depended on going
> forward? (e.g. are their unit tests which guarantee it?)
>
> Alternatively, is there a better way to get the value of a metric at the
> start of a particular time interval?

Sub-queries always align to multiples of the step (in Unix time). This
was essentially chosen as a mean to reduce the evaluation
cost. However, sometimes you might want to control the alignment. This
is what https://github.com/prometheus/prometheus/issues/9767 is about.

https://github.com/prometheus/prometheus/pull/17106 is a recent
attempt to implement it. (On my review list, but I would welcome other
reviewers, as my list is quite long. We had previous attempts that
didn't reach the goal.)

Circling back to your questions: I do believe that the current
alignment is something that we should consider a stable part of
PromQL, so you can rely on it. We should also document it more
clearly. And we should get
https://github.com/prometheus/prometheus/issues/9767 resolved so that
people can also do the other thing.

--
Björn Rabenstein
[PGP-ID] 0x851C3DA17D748D03
[email] bjo...@rabenste.in

[Brian Candler]

Very clear, thank you!