diff --git a/cmd/prometheus/testdata/features.json b/cmd/prometheus/testdata/features.json index e530770f8b..ae7490c5b7 100644 --- a/cmd/prometheus/testdata/features.json +++ b/cmd/prometheus/testdata/features.json @@ -100,7 +100,9 @@ "log10": true, "log2": true, "mad_over_time": false, + "max_of": false, "max_over_time": true, + "min_of": false, "min_over_time": true, "minute": true, "month": true, diff --git a/docs/feature_flags.md b/docs/feature_flags.md index 5304a30922..7771e02f6d 100644 --- a/docs/feature_flags.md +++ b/docs/feature_flags.md @@ -236,7 +236,10 @@ For a **range query**, it resolves to the full range of the query (end time - st For an **instant query**, it resolves to `0s`. This is particularly useful in combination with `@end()` to look back over the entire query range, e.g., `max_over_time(metric[range()] @ end())`. -`min(, )` and `max(, )` can be used to find the minimum or maximum of two duration expressions. +`min_of(, )` and `max_of(, )` select between two duration expressions. +`min_of` returns the smaller of the two, which is useful for capping a duration at a maximum value. +`max_of` returns the larger of the two, which is useful for enforcing a minimum value. +For example, `max_of(step(), 5s)` ensures the duration is never shorter than `5s`, while `min_of(range(), 1h)` caps the duration at `1h`. **Note**: Duration expressions are not supported in the @ timestamp operator. @@ -258,8 +261,8 @@ Examples of equivalent durations: * `4h % 3h` is equivalent to `1h` or `3600s` * `(2 ^ 3) * 1m` is equivalent to `8m` or `480s` * `step() + 1` is equivalent to the query step width increased by 1s. -* `max(step(), 5s)` is equivalent to the larger of the query step width and `5s`. -* `min(2 * step() + 5s, 5m)` is equivalent to the smaller of twice the query step increased by `5s` and `5m`. +* `max_of(step(), 5s)` is equivalent to the larger of the query step width and `5s`. +* `min_of(2 * step() + 5s, 5m)` is equivalent to the smaller of twice the query step increased by `5s` and `5m`. ## OTLP Native Delta Support diff --git a/docs/querying/functions.md b/docs/querying/functions.md index a175064b81..5900da4c62 100644 --- a/docs/querying/functions.md +++ b/docs/querying/functions.md @@ -693,6 +693,24 @@ This second example has the same effect than the first example, and illustrates label_replace(up{job="api-server",service="a:c"}, "foo", "$name", "service", "(?P.*):(?P.*)") ``` +## `max_of()` + +**This function has to be enabled via the [feature +flag](../feature_flags.md#experimental-promql-functions) +`--enable-feature=promql-experimental-functions`.** + +`max_of(a scalar, b scalar)` returns the larger of the two scalar values `a` +and `b`. + +## `min_of()` + +**This function has to be enabled via the [feature +flag](../feature_flags.md#experimental-promql-functions) +`--enable-feature=promql-experimental-functions`.** + +`min_of(a scalar, b scalar)` returns the smaller of the two scalar values `a` +and `b`. + ## `ln()` `ln(v instant-vector)` calculates the natural logarithm for all float samples diff --git a/promql/durations.go b/promql/durations.go index 3dc44fbbc6..f0319e1acd 100644 --- a/promql/durations.go +++ b/promql/durations.go @@ -135,9 +135,9 @@ func (v *durationVisitor) evaluateDurationExpr(expr parser.Expr) (float64, error return float64(v.step.Seconds()), nil case parser.RANGE: return float64(v.queryRange.Seconds()), nil - case parser.MIN: + case parser.MIN_OF: return math.Min(lhs, rhs), nil - case parser.MAX: + case parser.MAX_OF: return math.Max(lhs, rhs), nil case parser.ADD: if n.LHS == nil { diff --git a/promql/durations_test.go b/promql/durations_test.go index b8225ca8fc..0f4f4df652 100644 --- a/promql/durations_test.go +++ b/promql/durations_test.go @@ -228,7 +228,7 @@ func TestCalculateDuration(t *testing.T) { expected: 150 * time.Second, }, { - name: "max of step and range", + name: "max_of of step and range", expr: &parser.DurationExpr{ LHS: &parser.DurationExpr{ Op: parser.STEP, @@ -236,7 +236,7 @@ func TestCalculateDuration(t *testing.T) { RHS: &parser.DurationExpr{ Op: parser.RANGE, }, - Op: parser.MAX, + Op: parser.MAX_OF, }, expected: 5 * time.Minute, }, diff --git a/promql/functions.go b/promql/functions.go index 2c66263981..399f979cf7 100644 --- a/promql/functions.go +++ b/promql/functions.go @@ -1708,6 +1708,16 @@ func funcSqrt(vectorVals []Vector, _ Matrix, _ parser.Expressions, enh *EvalNode return simpleFloatFunc(vectorVals, enh, math.Sqrt), nil } +// === max_of(a, b parser.ValueTypeScalar) Scalar === +func funcMaxOf(vectorVals []Vector, _ Matrix, _ parser.Expressions, enh *EvalNodeHelper) (Vector, annotations.Annotations) { + return append(enh.Out, Sample{F: math.Max(vectorVals[0][0].F, vectorVals[1][0].F)}), nil +} + +// === min_of(a, b parser.ValueTypeScalar) Scalar === +func funcMinOf(vectorVals []Vector, _ Matrix, _ parser.Expressions, enh *EvalNodeHelper) (Vector, annotations.Annotations) { + return append(enh.Out, Sample{F: math.Min(vectorVals[0][0].F, vectorVals[1][0].F)}), nil +} + // === ln(Vector parser.ValueTypeVector) (Vector, Annotations) === func funcLn(vectorVals []Vector, _ Matrix, _ parser.Expressions, enh *EvalNodeHelper) (Vector, annotations.Annotations) { return simpleFloatFunc(vectorVals, enh, math.Log), nil @@ -2565,8 +2575,10 @@ var FunctionCalls = map[string]FunctionCall{ "increase": funcIncrease, "info": nil, "irate": funcIrate, + "max_of": funcMaxOf, "label_replace": nil, // evalLabelReplace not called via this map. "label_join": nil, // evalLabelJoin not called via this map. + "min_of": funcMinOf, "ln": funcLn, "log10": funcLog10, "log2": funcLog2, diff --git a/promql/parser/functions.go b/promql/parser/functions.go index 6935260826..3e34b71700 100644 --- a/promql/parser/functions.go +++ b/promql/parser/functions.go @@ -263,11 +263,23 @@ var Functions = map[string]*Function{ Variadic: -1, ReturnType: ValueTypeVector, }, + "max_of": { + Name: "max_of", + ArgTypes: []ValueType{ValueTypeScalar, ValueTypeScalar}, + ReturnType: ValueTypeScalar, + Experimental: true, + }, "last_over_time": { Name: "last_over_time", ArgTypes: []ValueType{ValueTypeMatrix}, ReturnType: ValueTypeVector, }, + "min_of": { + Name: "min_of", + ArgTypes: []ValueType{ValueTypeScalar, ValueTypeScalar}, + ReturnType: ValueTypeScalar, + Experimental: true, + }, "ln": { Name: "ln", ArgTypes: []ValueType{ValueTypeVector}, diff --git a/promql/parser/generated_parser.y b/promql/parser/generated_parser.y index 34ce028c1f..1b22593dd2 100644 --- a/promql/parser/generated_parser.y +++ b/promql/parser/generated_parser.y @@ -159,6 +159,8 @@ START END STEP RANGE +MAX_OF +MIN_OF %token preprocessorEnd // Counter reset hints. @@ -183,7 +185,7 @@ START_METRIC_SELECTOR // Type definitions for grammar rules. %type label_match_list %type label_matcher -%type aggregate_op grouping_label match_op maybe_label metric_identifier unary_op at_modifier_preprocessors string_identifier counter_reset_hint min_max +%type aggregate_op grouping_label match_op maybe_label metric_identifier unary_op at_modifier_preprocessors string_identifier counter_reset_hint max_of_min_of %type label_set metric %type label_set_list %type