mudhorn/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2025-03-05 20:59:13 -08:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

docs: Clarify PromQL interval changes

Browse source 
Signed-off-by: Owen Williams <owen.williams@grafana.com>
This commit is contained in:
Owen Williams 2025-01-14 11:32:22 -05:00
parent a3c7f72ad0
commit 8ef04882ca
1 changed files with 52 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

82
docs/migration.md
View file

@ -60,36 +60,58 @@ This document offers guidance on migrating from Prometheus 2.x to Prometheus 3.0
## PromQL ## PromQL
- The `.` pattern in regular expressions in PromQL matches newline characters. ### Regular expressions match newlines
With this change a regular expressions like `.*` matches strings that include
`\n`. This applies to matchers in queries and relabel configs. The `.` pattern in regular expressions in PromQL matches newline characters.
- For example, the following regular expressions now match the accompanying With this change a regular expressions like `.*` matches strings that include
strings, whereas in Prometheus v2 these combinations didn't match. `\n`. This applies to matchers in queries and relabel configs.
- `.*` additionally matches `foo\n` and `Foo\nBar`
- `foo.?bar` additionally matches `foo\nbar` For example, the following regular expressions now match the accompanying
- `foo.+bar` additionally matches `foo\nbar` strings, whereas in Prometheus v2 these combinations didn't match.
- If you want Prometheus v3 to behave like v2, you will have to change your - `.*` additionally matches `foo\n` and `Foo\nBar`
regular expressions by replacing all `.` patterns with `[^\n]`, e.g. - `foo.?bar` additionally matches `foo\nbar`
`foo[^\n]*`. - `foo.+bar` additionally matches `foo\nbar`
- Lookback and range selectors are left open and right closed (previously left
closed and right closed). This change affects queries when the evaluation time If you want Prometheus v3 to behave like v2, you will have to change your
perfectly aligns with the sample timestamps. For example assume querying a regular expressions by replacing all `.` patterns with `[^\n]`, e.g.
timeseries with evenly spaced samples exactly 1 minute apart. Before Prometheus `foo[^\n]*`.
v3, a range query with `5m` would usually return 5 samples. But if the query
evaluation aligns perfectly with a scrape, it would return 6 samples. In ### Intervals return a predictable number of points
Prometheus v3 queries like this will always return 5 samples.
This change has likely few effects for everyday use, except for some subquery Lookback and range selectors are now left-open and right-closed (previously
use cases. left-closed and right-closed), which affects queries whose evaluation time
Query front-ends that align queries usually align subqueries to multiples of perfectly aligns with the sample timestamps.
the step size. These subqueries will likely be affected.
Tests are more likely to affected. To fix those either adjust the expected For example, assume we are querying a timeseries with evenly spaced samples
number of samples or extend the range by less than one sample interval. exactly 1 minute apart. Before Prometheus v3, a range query with `5m` would
- The `holt_winters` function has been renamed to `double_exponential_smoothing` usually return 5 samples. But if the query evaluation aligns perfectly with a
and is now guarded by the `promql-experimental-functions` feature flag. scrape, it would return 6 samples. In Prometheus v3 queries like this will
If you want to keep using `holt_winters`, you have to do both of these things: always return 5 samples given even spacing.
- Rename `holt_winters` to `double_exponential_smoothing` in your queries.
- Pass `--enable-feature=promql-experimental-functions` in your Prometheus This change may affect subqueries that unintentionally relied on the old
CLI invocation. behavior, because query frontends often align subqueries to multiples of the
step size. Before Prometheus V3 a subquery of `foo[1m:1m]` on such a system
might have always returned two points, allowing for rate calculations. In
Prometheus V3, however, such a subquery will only return one point, which is
insufficient for a rate or increase calculation.
Such queries will need to be rewritten to extend the window to properly cover
more than one point. In the example above, `foo[2m:1m]` should return two points
no matter the query alignment. The exact form of the rewritten query may depend
on the intended results and the nature of the underlying data and there is no
universal drop-in replacement for queries whose behavior has changed.
Tests are similarly more likely to affected. To fix those either adjust the
expected number of samples or extend the range.
### holt_winters function renamed
The `holt_winters` function has been renamed to `double_exponential_smoothing`
and is now guarded by the `promql-experimental-functions` feature flag.
If you want to keep using `holt_winters`, you have to do both of these things:
- Rename `holt_winters` to `double_exponential_smoothing` in your queries.
- Pass `--enable-feature=promql-experimental-functions` in your Prometheus
CLI invocation.
## Scrape protocols ## Scrape protocols
Prometheus v3 is more strict concerning the Content-Type header received when Prometheus v3 is more strict concerning the Content-Type header received when