Prometheus: Invest in tests and docs for min interval or min step explanation (#80165)

* add clearer comment for function def

* update test to reflect change in range for 1w step

* clarify docs

* add more clarity

* add explanation to query options min interval and link to min step

* Update docs/sources/panels-visualizations/query-transform-data/_index.md

Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>

---------

Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>

docs/sources/datasources/prometheus/query-editor/index.md

@@ -74,7 +74,7 @@ The **Legend** setting defines the time series's name. You can use a predefined
 
 The **Min step** setting defines the lower bounds on the interval between data points.
 For example, set this to `1h` to hint that measurements are taken hourly.
-This setting supports the `$__interval` and `$__rate_interval` macros.
+This setting supports the `$__interval` and `$__rate_interval` macros. Be aware that the query range dates are aligned to the step and this can change the start and end of the range.
 
 ### Format
 
@@ -96,7 +96,7 @@ For more information, refer to the [Time Series Transform option documentation][
 
 {{% admonition type="note" %}}
 Grafana modifies the request dates for queries to align them with the dynamically calculated step.
-This ensures a consistent display of metrics data, but it can result in a small gap of data at the right edge of a graph.
+This ensures a consistent display of metrics data and Prometheus requires this for caching results. But, aligning the range with the step can result in a small gap of data at the right edge of a graph or change the start date of the range. For example, a 15s step aligns the range to Unix time divisible by 15s and a 1w minstep aligns the range to the start of the week on a Thursday.
 {{% /admonition %}}
 
 ### Exemplars

docs/sources/panels-visualizations/query-transform-data/_index.md

@@ -158,6 +158,11 @@ Panel data source query options include:
 - **Min interval:** Sets a minimum limit for the automatically calculated interval, which is typically the minimum scrape interval.
   If a data point is saved every 15 seconds, you don't benefit from having an interval lower than that.
   You can also set this to a higher minimum than the scrape interval to retrieve queries that are more coarse-grained and well-functioning.
+
+  {{% admonition type="note" %}}
+  The **Min interval** corresponds to the min step in Prometheus. Changing the Prometheus interval can change the start and end of the query range because Prometheus aligns the range to the interval. Refer to [Min step](https://grafana.com/docs/grafana/latest/datasources/prometheus/query-editor/#min-step) for more details.
+  {{% /admonition %}}
+
 - **Interval:** Sets a time span that you can use when aggregating or grouping data points by time.
 
   Grafana automatically calculates an appropriate interval that you can use as a variable in templated queries.

pkg/tsdb/prometheus/models/query.go

@@ -284,6 +284,11 @@ func isVariableInterval(interval string) bool {
 	return false
 }
 
+// This function aligns query range to step and handles the time offset.
+// It rounds start and end down to a multiple of step.
+// Prometheus caching is dependent on the range being aligned with the step.
+// Rounding to the step can significantly change the start and end of the range for larger steps, i.e. a week.
+// In rounding the range to a 1w step the range will always start on a Thursday.
 func AlignTimeRange(t time.Time, step time.Duration, offset int64) time.Time {
 	offsetNano := float64(offset * 1e9)
 	stepNano := float64(step.Nanoseconds())

pkg/tsdb/prometheus/models/query_test.go

@@ -739,20 +739,40 @@ func queryContext(json string, timeRange backend.TimeRange, queryInterval time.D
 	}
 }
 
+// AlignTimeRange aligns query range to step and handles the time offset.
+// It rounds start and end down to a multiple of step.
+// Prometheus caching is dependent on the range being aligned with the step.
+// Rounding to the step can significantly change the start and end of the range for larger steps, i.e. a week.
+// In rounding the range to a 1w step the range will always start on a Thursday.
 func TestAlignTimeRange(t *testing.T) {
 	type args struct {
 		t      time.Time
 		step   time.Duration
 		offset int64
 	}
+
+	var monday int64 = 1704672000
+	var thursday int64 = 1704326400
+	var one_week_min_step = 604800 * time.Second
+
 	tests := []struct {
 		name string
 		args args
 		want time.Time
 	}{
-		{name: "second step", args: args{t: time.Unix(1664816826, 0), step: 10 * time.Second, offset: 0}, want: time.Unix(1664816820, 0).UTC()},
+		{
+			name: "second step",
+			args: args{t: time.Unix(1664816826, 0), step: 10 * time.Second, offset: 0},
+			want: time.Unix(1664816820, 0).UTC(),
+		},
 		{name: "millisecond step", args: args{t: time.Unix(1664816825, 5*int64(time.Millisecond)), step: 10 * time.Millisecond, offset: 0}, want: time.Unix(1664816825, 0).UTC()},
 		{name: "second step with offset", args: args{t: time.Unix(1664816825, 5*int64(time.Millisecond)), step: 2 * time.Second, offset: -3}, want: time.Unix(1664816825, 0).UTC()},
+		// we may not want this functionality in the future but if we change this we break Prometheus caching.
+		{
+			name: "1w step with range date of Monday that changes the range to a Thursday.",
+			args: args{t: time.Unix(monday, 0), step: one_week_min_step, offset: 0},
+			want: time.Unix(thursday, 0).UTC(),
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {