mudhorn/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2025-02-02 08:31:11 -08:00
Code Issues Actions 55 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 7be00791ef
commit 8071cebff6
1 changed files with 50 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

80
docs/migration.md
View file

@ -60,36 +60,56 @@ 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. ### Regexes 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 Interval selectors are now more predictable than they were previously, always
use cases. returning the same number of points regardless of query alignment.
Query front-ends that align queries usually align subqueries to multiples of
the step size. These subqueries will likely be affected. Lookback and range selectors are now left-open and right-closed (previously
Tests are more likely to affected. To fix those either adjust the expected left-closed and right-closed). This change affects queries when the evaluation
number of samples or extend the range by less than one sample interval. time perfectly aligns with the sample timestamps.
- The `holt_winters` function has been renamed to `double_exponential_smoothing`
and is now guarded by the `promql-experimental-functions` feature flag. For example, assume we are querying a timeseries with evenly spaced samples
If you want to keep using `holt_winters`, you have to do both of these things: exactly 1 minute apart. Before Prometheus v3, a range query with `5m` would
- Rename `holt_winters` to `double_exponential_smoothing` in your queries. usually return 5 samples. But if the query evaluation aligns perfectly with a
- Pass `--enable-feature=promql-experimental-functions` in your Prometheus scrape, it would return 6 samples. In Prometheus v3 queries like this will
CLI invocation. always return 5 samples.
This change may affect subqueries that unintentionally relied on the old
behavior. Query front-ends 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. Such queries will
need to be rewritten to extend the window to properly cover more than one point.
In this case, `foo[2m:1m]` would always return two points no matter the query
alignment.
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