From 8071cebff649b98695a974896888bc566422e4e7 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 | 80 +++++++++++++++++++++++++++++------------------ 1 file changed, 50 insertions(+), 30 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index e2d53472f..00cefeaad 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -60,36 +60,56 @@ 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. +### Regexes 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 + +Interval selectors are now more predictable than they were previously, always +returning the same number of points regardless of query alignment. + +Lookback and range selectors are now 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 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. + +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 Prometheus v3 is more strict concerning the Content-Type header received when