Add support for extended range selector modifiers smoothed & anchored

CHANGELOG.md

@@ -28,6 +28,7 @@
 * [FEATURE] Query-frontends: Automatically adjust features used in query plans generated for remote execution based on what the available queriers support. #13017 #13164
 * [FEATURE] Memberlist: Add experimental support for zone-aware routing, in order to reduce memberlist cross-AZ data transfer. #13129
 * [FEATURE] Query-frontend and querier: Add experimental support for performing query planning in query-frontends and distributing portions of the plan to queriers for execution. #13058
+* [FEATURE] MQE: Add support for experimental extended range selector modifiers `smoothed` and `anchored`. These can be enabled with `-query-frontend.enabled-promql-extended-range-selectors=smoothed,anchored` #13398
 * [FEATURE] Querier: Add `querier.mimir-query-engine.enable-reduce-matchers` flag that enables a new MQE AST optimization pass that eliminates duplicate or redundant matchers that are part of selector expressions. #13178
 * [ENHANCEMENT] Compactor, Store-gateway: Change default value of `-compactor.upload-sparse-index-headers` to `true`. This improves lazy loading performance in the store-gateway. #13089
 * [ENHANCEMENT] Store-gateway: Verify CRC32 checksums for 1 out of every 128 chunks read from object storage and the chunks cache to detect corruption. #13151
@@ -55,6 +56,7 @@
   * `-ruler-storage.gcs.max-retries`
 * [ENHANCEMENT] Usage-tracker: Improve first snapshot loading & rehash speed. #13284
 * [ENHANCEMENT] Ruler: Implemented `OperatorControllableErrorClassifier` for rule evaluation, allowing differentiation between operator-controllable errors (e.g., storage failures, 5xx errors, rate limiting) and user-controllable errors (e.g., bad queries, validation errors, 4xx errors). This change affects the rule evaluation failure metric `prometheus_rule_evaluation_failures_total`, which now includes a `reason` label with values `operator` or `user` to distinguish between them. #13313
+* [ENHANCEMENT] Query-frontend: Limits middleware will record different error messages when experimental functions, aggregations, or extended range selector modifiers are used but not enabled for a tenant. #13398
 * [BUGFIX] Compactor: Fix potential concurrent map writes. #13053
 * [BUGFIX] Query-frontend: Fix issue where queries sometimes fail with `failed to receive query result stream message: rpc error: code = Canceled desc = context canceled` if remote execution is enabled. #13084
 * [BUGFIX] Query-frontend: Fix issue where query stats, such as series read, did not include the parameters to the `histogram_quantile` and `histogram_fraction` functions if remote execution was enabled. #13084

cmd/mimir/help-all.txt.tmpl

@@ -2349,6 +2349,8 @@ Usage of ./cmd/mimir/mimir:
     	[experimental] If set to true and the Mimir query engine is in use, use remote execution to evaluate queries in queriers.
   -query-frontend.enabled-promql-experimental-functions comma-separated-list-of-strings
     	Enable certain experimental PromQL functions, which are subject to being changed or removed at any time, on a per-tenant basis. Defaults to empty which means all experimental functions are disabled. Set to 'all' to enable all experimental functions.
+  -query-frontend.enabled-promql-extended-range-selectors  comma-separated-list-of-strings
+          Enable certain experimental PromQL range selector modifiers, which are subject to being changed or removed at any time, on a per-tenant basis. Defaults to empty which means all experimental modifiers are disabled. Set to 'all' to enable all experimental modifiers.
   -query-frontend.extra-propagated-headers comma-separated-list-of-strings
     	Comma-separated list of request header names to allow to pass through to the rest of the query path. This is in addition to a list of required headers that the read path needs.
   -query-frontend.grpc-client-config.backoff-max-period duration

cmd/mimir/help.txt.tmpl

@@ -603,6 +603,8 @@ Usage of ./cmd/mimir/mimir:
     	Cache statistics of processed samples on results cache.
   -query-frontend.enabled-promql-experimental-functions comma-separated-list-of-strings
     	Enable certain experimental PromQL functions, which are subject to being changed or removed at any time, on a per-tenant basis. Defaults to empty which means all experimental functions are disabled. Set to 'all' to enable all experimental functions.
+  -query-frontend.enabled-promql-extended-range-selectors  comma-separated-list-of-strings
+        Enable certain experimental PromQL range selector modifiers, which are subject to being changed or removed at any time, on a per-tenant basis. Defaults to empty which means all experimental modifiers are disabled. Set to 'all' to enable all experimental modifiers.
   -query-frontend.log-queries-longer-than duration
     	Log queries that are slower than the specified duration. Set to 0 to disable. Set to < 0 to enable on all queries.
   -query-frontend.max-queriers-per-tenant int

docs/sources/mimir/configure/about-versioning.md

@@ -210,6 +210,7 @@ The following features are currently experimental:
   - Remote execution of queries in queriers: `-query-frontend.enable-remote-execution=true`
   - Performing query sharding within MQE: `-query-frontend.use-mimir-query-engine-for-sharding=true`
   - Rewriting of queries to optimize processing: `-query-frontend.rewrite-histogram-queries` and `-query-frontend.rewrite-propagate-matchers`
+  - Enable experimental Prometheus extended range selector modifiers `smoothed` and `anchored` (`-query-frontend.enabled-promql-extended-range-selectors=smoothed,anchored`)
 - Query-scheduler
   - `-query-scheduler.querier-forget-delay`
 - Store-gateway

docs/sources/mimir/configure/configuration-parameters/index.md

@@ -3986,6 +3986,13 @@ blocked_requests:
 # CLI flag: -query-frontend.enabled-promql-experimental-functions
 [enabled_promql_experimental_functions: <string> | default = ""]
 
+# Enable certain experimental PromQL extended range selector modifiers, which
+# are subject to being changed or removed at any time, on a per-tenant basis.
+# Defaults to empty which means all experimental modifiers are disabled. Set to
+# 'all' to enable all experimental modifiers.
+# CLI flag: -query-frontend.enabled-promql-extended-range-selectors
+[enabled_promql_extended_range_selectors: <string> | default = ""]
+
 # (experimental) Rewrite queries using the same range selector and resolution
 # [X:X] which don't work in Prometheus 3.0 to a nearly identical form that works
 # with Prometheus 3.0 semantics

pkg/frontend/querymiddleware/astmapper/astmapper.go

@@ -144,6 +144,8 @@ func cloneExpr(expr parser.Expr) (parser.Expr, error) {
 			LabelMatchers:           matchers,
 			BypassEmptyMatcherCheck: e.BypassEmptyMatcherCheck,
 			PosRange:                e.PosRange,
+			Anchored:                e.Anchored,
+			Smoothed:                e.Smoothed,
 		}, nil
 
 	case *parser.MatrixSelector:

pkg/frontend/querymiddleware/astmapper/astmapper_test.go

@@ -139,6 +139,12 @@ func TestCloneExpr(t *testing.T) {
 		`foo and bar`,
 		`foo == bar`,
 		`foo == bool bar`,
+
+		// Range modifiers
+		`metric[1m] anchored`,
+		`metric[1m] smoothed`,
+		`rate(metric[1m] anchored)`,
+		`increase(metric[1m] smoothed)`,
 	}
 
 	for i, tc := range testCases {
@@ -245,11 +251,14 @@ func loadTestExpressionsFromDirectory(t *testing.T, dir string, accumulatedExpre
 func enableExperimentalParserFeaturesDuringTest(t *testing.T) {
 	oldDurationExpressions := parser.ExperimentalDurationExpr
 	oldExperimentalFunctions := parser.EnableExperimentalFunctions
+	oldEnableExtendedRangeSelectors := parser.EnableExtendedRangeSelectors
 	parser.ExperimentalDurationExpr = true
 	parser.EnableExperimentalFunctions = true
+	parser.EnableExtendedRangeSelectors = true
 	t.Cleanup(func() {
 		parser.ExperimentalDurationExpr = oldDurationExpressions
 		parser.EnableExperimentalFunctions = oldExperimentalFunctions
+		parser.EnableExtendedRangeSelectors = oldEnableExtendedRangeSelectors
 	})
 }
 

pkg/frontend/querymiddleware/experimental_functions.go

@@ -16,6 +16,9 @@ import (
 
 const (
 	allExperimentalFunctions = "all"
+	isFunction               = 1
+	isAggregator             = 2
+	isExtendedRangeSelector  = 3
 )
 
 type experimentalFunctionsMiddleware struct {
@@ -26,6 +29,7 @@ type experimentalFunctionsMiddleware struct {
 
 // newExperimentalFunctionsMiddleware creates a middleware that blocks queries that contain PromQL experimental functions
 // that are not enabled for the active tenant(s), allowing us to enable specific functions only for selected tenants.
+// This middleware also manages blocking queries that contain PromQL experimental aggregates and extended range selector modifiers.
 func newExperimentalFunctionsMiddleware(limits Limits, logger log.Logger) MetricsQueryMiddleware {
 	return MetricsQueryMiddlewareFunc(func(next MetricsQueryHandler) MetricsQueryHandler {
 		return &experimentalFunctionsMiddleware{
@@ -52,7 +56,17 @@ func (m *experimentalFunctionsMiddleware) Do(ctx context.Context, req MetricsQue
 		}
 	}
 
-	if allExperimentalFunctionsEnabled {
+	enabledExtendedRangeSelectors := make(map[string][]string, len(tenantIDs))
+	allExtendedRangeSelectorsEnabled := true
+	for _, tenantID := range tenantIDs {
+		enabled := m.limits.EnabledPromQLExtendedRangeSelectors(tenantID)
+		enabledExtendedRangeSelectors[tenantID] = enabled
+		if len(enabled) == 0 || enabled[0] != allExperimentalFunctions {
+			allExtendedRangeSelectorsEnabled = false
+		}
+	}
+
+	if allExperimentalFunctionsEnabled && allExtendedRangeSelectorsEnabled {
 		// If all experimental functions are enabled for all tenants here, we don't need to check the query
 		// for those functions and can skip this middleware.
 		return m.next.Do(ctx, req)
@@ -68,17 +82,24 @@ func (m *experimentalFunctionsMiddleware) Do(ctx context.Context, req MetricsQue
 		return m.next.Do(ctx, req)
 	}
 
-	// Make sure that every used experimental function is enabled for all the tenants here.
-	for name := range funcs {
-		for tenantID, enabled := range enabledExperimentalFunctions {
+	// Make sure that every used experimental function/modifier is enabled for all the tenants here.
+	var tenantMap map[string][]string
+	for name, t := range funcs {
+		switch t {
+		case isFunction, isAggregator:
+			tenantMap = enabledExperimentalFunctions
+		case isExtendedRangeSelector:
+			tenantMap = enabledExtendedRangeSelectors
+		}
+
+		for tenantID, enabled := range tenantMap {
 			if len(enabled) > 0 && enabled[0] == allExperimentalFunctions {
 				// If the first item matches the const value of allExperimentalFunctions, then all experimental
 				// functions are enabled for this tenant.
 				continue
 			}
 			if !slices.Contains(enabled, name) {
-				err := fmt.Errorf("function %q is not enabled for tenant %s", name, tenantID)
-				return nil, apierror.New(apierror.TypeBadData, DecorateWithParamName(err, "query").Error())
+				return nil, raiseError(tenantID, name, t)
 			}
 		}
 	}
@@ -87,18 +108,45 @@ func (m *experimentalFunctionsMiddleware) Do(ctx context.Context, req MetricsQue
 	return m.next.Do(ctx, req)
 }
 
+func raiseError(tenantID string, name string, t int) error {
+	switch t {
+	case isFunction:
+		err := fmt.Errorf("function %q is not enabled for tenant %s", name, tenantID)
+		return apierror.New(apierror.TypeBadData, DecorateWithParamName(err, "query").Error())
+	case isAggregator:
+		err := fmt.Errorf("aggregate %q is not enabled for tenant %s", name, tenantID)
+		return apierror.New(apierror.TypeBadData, DecorateWithParamName(err, "query").Error())
+	case isExtendedRangeSelector:
+		err := fmt.Errorf("extended range selector modifier %q is not enabled for tenant %s", name, tenantID)
+		return apierror.New(apierror.TypeBadData, DecorateWithParamName(err, "query").Error())
+	}
+	return nil
+}
+
 // containedExperimentalFunctions returns any PromQL experimental functions used in the query.
-func containedExperimentalFunctions(expr parser.Expr) map[string]struct{} {
-	expFuncNames := map[string]struct{}{}
+func containedExperimentalFunctions(expr parser.Expr) map[string]int {
+	expFuncNames := map[string]int{}
 	_ = inspect(expr, func(node parser.Node) error {
 		switch n := node.(type) {
 		case *parser.Call:
 			if parser.Functions[n.Func.Name].Experimental {
-				expFuncNames[n.Func.Name] = struct{}{}
+				expFuncNames[n.Func.Name] = isFunction
 			}
 		case *parser.AggregateExpr:
 			if n.Op.IsExperimentalAggregator() {
-				expFuncNames[n.Op.String()] = struct{}{}
+				expFuncNames[n.Op.String()] = isAggregator
+			}
+		case *parser.MatrixSelector:
+			// technically anchored & smoothed are range selectors not functions
+			vs, ok := n.VectorSelector.(*parser.VectorSelector)
+			if ok && vs.Anchored {
+				expFuncNames["anchored"] = isExtendedRangeSelector
+			} else if ok && vs.Smoothed {
+				expFuncNames["smoothed"] = isExtendedRangeSelector
+			}
+		case *parser.VectorSelector:
+			if n.Smoothed {
+				expFuncNames["smoothed"] = isExtendedRangeSelector
 			}
 		}
 		return nil

pkg/frontend/querymiddleware/experimental_functions_test.go

@@ -10,53 +10,96 @@ import (
 )
 
 func TestContainedExperimentalFunctions(t *testing.T) {
-	t.Cleanup(func() { parser.EnableExperimentalFunctions = false })
+	t.Cleanup(func() {
+		parser.EnableExperimentalFunctions = false
+		parser.EnableExtendedRangeSelectors = false
+	})
 	parser.EnableExperimentalFunctions = true
+	parser.EnableExtendedRangeSelectors = true
 
 	testCases := map[string]struct {
 		query  string
 		expect []string
+		err    string
 	}{
 		"sum by": {
 			query: `sum(up) by (namespace)`,
+			err:   "function \"sum by\" is not enabled for tenant tenant",
 		},
 		"mad_over_time": {
 			query:  `mad_over_time(up[5m])`,
 			expect: []string{"mad_over_time"},
+			err:    "function \"mad_over_time\" is not enabled for tenant tenant",
 		},
 		"mad_over_time with sum and by": {
 			query:  `sum(mad_over_time(up[5m])) by (namespace)`,
 			expect: []string{"mad_over_time"},
+			err:    "function \"mad_over_time\" is not enabled for tenant tenant",
 		},
 		"sort_by_label": {
 			query:  `sort_by_label({__name__=~".+"}, "__name__")`,
 			expect: []string{"sort_by_label"},
+			err:    "function \"sort_by_label\" is not enabled for tenant tenant",
 		},
 		"sort_by_label_desc": {
 			query:  `sort_by_label_desc({__name__=~".+"}, "__name__")`,
 			expect: []string{"sort_by_label_desc"},
+			err:    "function \"sort_by_label_desc\" is not enabled for tenant tenant",
 		},
 		"limitk": {
 			query:  `limitk by (group) (0, up)`,
 			expect: []string{"limitk"},
+			err:    "aggregate \"limitk\" is not enabled for tenant tenant",
 		},
 		"limit_ratio": {
 			query:  `limit_ratio(0.5, up)`,
 			expect: []string{"limit_ratio"},
+			err:    "aggregate \"limit_ratio\" is not enabled for tenant tenant",
 		},
 		"limit_ratio with mad_over_time": {
 			query:  `limit_ratio(0.5, mad_over_time(up[5m]))`,
 			expect: []string{"limit_ratio", "mad_over_time"},
 		},
+		"metric smoothed": {
+			query:  `metric smoothed`,
+			expect: []string{"smoothed"},
+			err:    "extended range selector modifier \"smoothed\" is not enabled for tenant tenant",
+		},
+		"metric[1m] smoothed": {
+			query:  `metric[1m] smoothed`,
+			expect: []string{"smoothed"},
+			err:    "extended range selector modifier \"smoothed\" is not enabled for tenant tenant",
+		},
+		"metric[1m] anchored": {
+			query:  `metric[1m] anchored`,
+			expect: []string{"anchored"},
+			err:    "extended range selector modifier \"anchored\" is not enabled for tenant tenant",
+		},
+		"rate(metric[1m] smoothed)": {
+			query:  `rate(metric[1m] smoothed)`,
+			expect: []string{"smoothed"},
+			err:    "extended range selector modifier \"smoothed\" is not enabled for tenant tenant",
+		},
+		"increase(metric[1m] anchored)": {
+			query:  `increase(metric[1m] anchored)`,
+			expect: []string{"anchored"},
+			err:    "extended range selector modifier \"anchored\" is not enabled for tenant tenant",
+		},
 	}
 
 	for name, tc := range testCases {
 		t.Run(name, func(t *testing.T) {
 			expr, err := parser.ParseExpr(tc.query)
 			require.NoError(t, err)
 			var enabled []string
-			for key := range containedExperimentalFunctions(expr) {
+			for key, funcType := range containedExperimentalFunctions(expr) {
 				enabled = append(enabled, key)
+				if len(tc.err) > 0 {
+					// test that if an error was raised for this function/aggregate/modifier that the expected error string is formed
+					// an empty tc.err allows for the case to be skipped - such as where we have multiple errors which are validated elsewhere
+					err := raiseError("tenant", key, funcType)
+					require.ErrorContains(t, err, tc.err)
+				}
 			}
 			require.ElementsMatch(t, tc.expect, enabled)
 		})

pkg/frontend/querymiddleware/limits.go

@@ -101,6 +101,9 @@ type Limits interface {
 	// EnabledPromQLExperimentalFunctions returns the names of PromQL experimental functions allowed for the tenant.
 	EnabledPromQLExperimentalFunctions(userID string) []string
 
+	// EnabledPromQLExtendedRangeSelectors returns the names of PromQL experimental extended range selectors modifiers allowed for the tenant.
+	EnabledPromQLExtendedRangeSelectors(userID string) []string
+
 	// Prom2RangeCompat returns if Prometheus 2/3 range compatibility fixes are enabled for the tenant.
 	Prom2RangeCompat(userID string) bool
 

pkg/frontend/querymiddleware/limits_test.go

@@ -675,6 +675,10 @@ func (m multiTenantMockLimits) EnabledPromQLExperimentalFunctions(userID string)
 	return m.byTenant[userID].enabledPromQLExperimentalFunctions
 }
 
+func (m multiTenantMockLimits) EnabledPromQLExtendedRangeSelectors(userID string) []string {
+	return m.byTenant[userID].enabledPromQLExtendedRangeSelectors
+}
+
 func (m multiTenantMockLimits) Prom2RangeCompat(userID string) bool {
 	return m.byTenant[userID].prom2RangeCompat
 }
@@ -741,6 +745,7 @@ type mockLimits struct {
 	resultsCacheTTLForErrors             time.Duration
 	resultsCacheForUnalignedQueryEnabled bool
 	enabledPromQLExperimentalFunctions   []string
+	enabledPromQLExtendedRangeSelectors  []string
 	prom2RangeCompat                     bool
 	blockedQueries                       []validation.BlockedQuery
 	limitedQueries                       []validation.LimitedQuery
@@ -838,6 +843,10 @@ func (m mockLimits) EnabledPromQLExperimentalFunctions(string) []string {
 	return m.enabledPromQLExperimentalFunctions
 }
 
+func (m mockLimits) EnabledPromQLExtendedRangeSelectors(string) []string {
+	return m.enabledPromQLExtendedRangeSelectors
+}
+
 func (m mockLimits) Prom2RangeCompat(string) bool {
 	return m.prom2RangeCompat
 }

pkg/frontend/querymiddleware/roundtrip.go

@@ -264,6 +264,9 @@ func newQueryTripperware(
 	// This enables duration arithmetic https://github.com/prometheus/prometheus/pull/16249.
 	parser.ExperimentalDurationExpr = true
 
+	// This enables the anchored and smoothed selector modifiers
+	parser.EnableExtendedRangeSelectors = true
+
 	var c cache.Cache
 	if cfg.CacheResults || cfg.cardinalityBasedShardingEnabled() {
 		var err error

pkg/querier/querier.go

@@ -197,6 +197,9 @@ func New(cfg Config, limits *validation.Overrides, distributor Distributor, quer
 	// This enables duration arithmetic https://github.com/prometheus/prometheus/pull/16249.
 	parser.ExperimentalDurationExpr = true
 
+	// This enables the anchored and smoothed selector modifiers
+	parser.EnableExtendedRangeSelectors = true
+
 	var eng promql.QueryEngine
 	var streamingEngine *streamingpromql.Engine