From 8ef04882ca7e15f654dca98abddccafff46c8428 Mon Sep 17 00:00:00 2001 From: Owen Williams Date: Tue, 14 Jan 2025 11:32:22 -0500 Subject: [PATCH] docs: Clarify PromQL interval changes Signed-off-by: Owen Williams --- docs/migration.md | 82 ++++++++++++++++++++++++++++++----------------- 1 file changed, 52 insertions(+), 30 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index e2d53472f3..501eb46e0b 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -60,36 +60,58 @@ This document offers guidance on migrating from Prometheus 2.x to Prometheus 3.0 ## PromQL -- The `.` pattern in regular expressions in PromQL matches newline characters. - With this change a regular expressions like `.*` matches strings that include - `\n`. This applies to matchers in queries and relabel configs. - - For example, the following regular expressions now match the accompanying - strings, whereas in Prometheus v2 these combinations didn't match. - - `.*` additionally matches `foo\n` and `Foo\nBar` - - `foo.?bar` additionally matches `foo\nbar` - - `foo.+bar` additionally matches `foo\nbar` - - If you want Prometheus v3 to behave like v2, you will have to change your - regular expressions by replacing all `.` patterns with `[^\n]`, e.g. - `foo[^\n]*`. -- Lookback and range selectors are left open and right closed (previously left - closed and right closed). This change affects queries when the evaluation time - perfectly aligns with the sample timestamps. For example assume querying a - timeseries with evenly spaced samples exactly 1 minute apart. Before Prometheus - 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 - Prometheus v3 queries like this will always return 5 samples. - This change has likely few effects for everyday use, except for some subquery - use cases. - Query front-ends that align queries usually align subqueries to multiples of - the step size. These subqueries will likely be affected. - Tests are more likely to affected. To fix those either adjust the expected - number of samples or extend the range by less than one sample interval. -- 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. +### Regular expressions match newlines + +The `.` pattern in regular expressions in PromQL matches newline characters. +With this change a regular expressions like `.*` matches strings that include +`\n`. This applies to matchers in queries and relabel configs. + +For example, the following regular expressions now match the accompanying +strings, whereas in Prometheus v2 these combinations didn't match. + - `.*` additionally matches `foo\n` and `Foo\nBar` + - `foo.?bar` additionally matches `foo\nbar` + - `foo.+bar` additionally matches `foo\nbar` + +If you want Prometheus v3 to behave like v2, you will have to change your +regular expressions by replacing all `.` patterns with `[^\n]`, e.g. +`foo[^\n]*`. + +### Intervals return a predictable number of points + +Lookback and range selectors are now left-open and right-closed (previously +left-closed and right-closed), which affects queries whose evaluation time +perfectly aligns with the sample timestamps. + +For example, assume we are querying a timeseries with evenly spaced samples +exactly 1 minute apart. Before Prometheus 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 Prometheus v3 queries like this will +always return 5 samples given even spacing. + +This change may affect subqueries that unintentionally relied on the old +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 Prometheus v3 is more strict concerning the Content-Type header received when