docs: clarify PromQL interval changes (#15824)

docs: Clarify PromQL interval changes

---------

Signed-off-by: Owen Williams <owen.williams@grafana.com>
Signed-off-by: Owen Williams <owen-github@ywwg.com>
Co-authored-by: Björn Rabenstein <beorn@grafana.com>

docs/migration.md

@@ -60,33 +60,60 @@ 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. 
+### 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.
+
+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.
+If you want Prometheus v3 to behave like v2, you will have to change your
-  `foo[^\n]*`.
+regular expressions by replacing all `.` patterns with `[^\n]`, e.g.
-- Lookback and range selectors are left open and right closed (previously left 
+`foo[^\n]*`.
-  closed and right closed). This change affects queries when the evaluation time 
+
-  perfectly aligns with the sample timestamps. For example assume querying a 
+### Range selectors and lookback exclude samples coinciding with the left boundary
-  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
+Lookback and range selectors are now left-open and right-closed (previously
-  evaluation aligns perfectly with a scrape, it would return 6 samples. In 
+left-closed and right-closed), which makes their behavior more consistent. This
-  Prometheus v3 queries like this will always return 5 samples.  
+change affects queries where the left boundary of a range or the lookback delta
-  This change has likely few effects for everyday use, except for some subquery
+coincides with the timestamp of one or more samples.
-  use cases.  
+
-  Query front-ends that align queries usually align subqueries to multiples of
+For example, assume we are querying a timeseries with evenly spaced samples
-  the step size. These subqueries will likely be affected.  
+exactly 1 minute apart. Before Prometheus v3, a range query with `5m` would
-  Tests are more likely to affected. To fix those either adjust the expected 
+usually return 5 samples. But if the query evaluation aligns perfectly with a
-  number of samples or extend the range by less than one sample interval.
+scrape, it would return 6 samples. In Prometheus v3 queries like this will
-- The `holt_winters` function has been renamed to `double_exponential_smoothing` 
+always return 5 samples given even spacing.
-  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:
+This change will typically affect subqueries because their evaluation timing is
+naturally perfectly evenly spaced and aligned with timestamps that are multiples
+of the subquery resolution. Furthermore, query frontends often align subqueries
+to multiples of the step size. In combination, this easily creates a situation
+of perfect mutual alignment, often unintended and unknown by the user, so that
+the new behavior might come as a surprise. 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,
+resulting in No Data returned.
+
+Such queries will need to be rewritten to extend the window to properly cover
+more than one point. In this example, `foo[2m:1m]` would always return two
+points no matter the query alignment. The exact form of the rewritten query may
+depend on the intended results 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.