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>

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) {