From 5c250c15da14c21a0c5aa208441657d9ba263985 Mon Sep 17 00:00:00 2001 From: Aditya Tiwari Date: Thu, 11 Sep 2025 19:36:38 +0530 Subject: [PATCH] docs(querying): add atan2 examples/notes; link trig functions Add Examples and Notes under trigonometric binary operators (operators.md): radians/degrees, atan2(y,x) order, vector matching, precedence, histogram behavior. Add cross-link from trig functions to operator examples (functions.md). Signed-off-by: Aditya Tiwari --- docs/querying/functions.md | 2 ++ docs/querying/operators.md | 26 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/docs/querying/functions.md b/docs/querying/functions.md index 4776490e5a..e61e7726d0 100644 --- a/docs/querying/functions.md +++ b/docs/querying/functions.md @@ -916,3 +916,5 @@ The following are useful for converting between degrees and radians: * `deg(v instant-vector)`: converts radians to degrees for all float samples in `v`. * `pi()`: returns pi. * `rad(v instant-vector)`: converts degrees to radians for all float samples in `v`. + +See also the [trigonometric binary operators](operators.md#trigonometric-binary-operators) for examples of `atan2` with vector matching. diff --git a/docs/querying/operators.md b/docs/querying/operators.md index 674cbf566c..b189949ca6 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -115,6 +115,32 @@ samples. Operations involving histogram samples result in the removal of the corresponding vector elements from the output vector, flagged by an info-level annotation. +#### Examples + + # Scalar/scalar: returns an angle in radians; convert to degrees for readability + deg(atan2(1, 0)) + # => 90 + + # Vector/scalar: apply atan2 to each float sample in a vector against a constant x + # (inputs/outputs are in radians; use rad()/deg() helpers as needed) + atan2(sin(rad(30)), 1) + + # Vector/vector with matching: match y- and x-components by labels + # Note the argument order: atan2(y, x) + y_component atan2 on(job, instance) x_component + + # Degrees vs radians: convert degrees to radians for inputs, and radians to degrees for output + deg(atan2(sin(rad(45)), cos(rad(45)))) + # => 45 + +#### Notes + +- `atan2(y, x)` expects arguments in the order y, then x. +- All angles are in radians. Use `rad()` to convert degrees to radians and `deg()` to convert back; `pi()` is available. +- Only float samples are supported. If an operation involves a histogram sample, the corresponding element is removed (info-level annotation). +- Operator precedence: `atan2` shares precedence with `*`, `/`, `%`. Use parentheses in mixed expressions to avoid ambiguity. +- Vector matching rules apply as with arithmetic operators. Use `on(...)`/`ignoring(...)` and `group_left`/`group_right` as needed. + ### Comparison binary operators The following binary comparison operators exist in Prometheus: