Math

Arithmetic Data Analysis

Synopsis

Performs mathematical operations on numeric values.

Schema

- math:
    field: <ident>
    operation: <string>
    left_operand: <string>
    right_operand: <string>
    precision: <numeric>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Target field to store the calculation result
operation	Y	-	Mathematical operation to perform
left_operand	Y	-	First operand value or field reference
right_operand	N	-	Second operand value or field reference (required for binary operations)
precision	N	0	Number of decimal places for rounding operations
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if calculation fails
ignore_missing	N	false	Skip if referenced fields don't exist
on_failure	N	-	Error handling processors
on_success	N	-	Success handling processors
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

warning

This operand is resolved by getNumericValue, which accepts exactly two forms: a numeric literal such as 3600, or a bare field path such as stats.total. Nothing else is evaluated.

There is no expression evaluator here, and no template expansion. "a / b" is looked up as a field literally named a / b, and "{{price}}" as a field literally named {{price}} — both fail with field does not exist. To compute a value first, use a math processor and reference the field it writes.

Supported Operations

Binary Operations (two operands)

Operation	Aliases	Description
add	+	Addition
subtract	-	Subtraction
multiply	*	Multiplication
divide	/	Division
modulo	%	Remainder after division
pow	^	Exponentiation (power)
min	-	Minimum of two values
max	-	Maximum of two values
bit_and	-	Bitwise AND
bit_or	-	Bitwise OR
bit_xor	-	Bitwise XOR
shift_left	-	Left shift, by the number of positions in the right operand
shift_right	-	Right shift, by the number of positions in the right operand

Unary Operations (one operand)

Operation	Description
abs	Absolute value
sqrt	Square root
ceil	Round up to nearest integer
floor	Round down to nearest integer
round	Round to nearest integer or decimal places (using precision)
bit_not	Bitwise NOT of the left operand

Details

Performs mathematical operations on numeric values and stores the result in a target field. The processor supports both binary operations (requiring two operands) and unary operations (requiring a single operand).

note

Numeric values are converted for calculation: an operand may be a number, a numeric string, or a boolean (true is 1, false is 0). An operand is either a numeric literal or a field reference and nothing more — field1 / field2 is not an expression, it is a lookup for a field with that exact name. Chain a second math processor when you need a compound calculation.

The processor can extract values from existing fields, use literal numeric values, and applies appropriate error handling for mathematical edge cases like division by zero or invalid operations.

Bitwise and shift operations

The five bitwise operations and bit_not read native 64-bit integers rather than going through the float64 arithmetic path, so they keep full precision beyond 2^53 where the other operations would not. The result is an integer.

A shift count is masked to 6 bits, following C#/Kusto 64-bit semantics: shifting by 64 is a shift by 0, not a shift to zero as Go's own saturating shift would give. A negative shift count is an error.

warning

Some operations have mathematical constraints and will fail in certain conditions:

• Division or modulo by zero
• Square root of negative numbers
• 0 raised to the power of 0 (indeterminate)
• Negative numbers raised to non-integer powers

Always provide appropriate error handling for operations that might encounter these edge cases.

Examples

Basic

Performing addition with literal values...	{ "metrics": {} } - math: field: metrics.total operation: add left_operand: "100" right_operand: "50"
calculates and stores the result:	{ "metrics": { "total": 150 } }

Field-Based

Calculating percentage from field values...	{ "disk": { "used": 8589934592, "total": 17179869184 } } - math: field: disk._ratio operation: divide left_operand: disk.used right_operand: disk.total - math: field: disk.usage_percent operation: multiply left_operand: disk._ratio right_operand: "100" precision: 2
computes disk usage percentage:	{ "disk": { "used": 8589934592, "total": 17179869184, "usage_percent": 50 } }

Unary

Applying unary operations...	{ "temperature": { "celsius": -5.7 } } - math: field: temperature.absolute operation: abs left_operand: "temperature.celsius"
calculates absolute value:	{ "temperature": { "celsius": -5.7, "absolute": 5.7 } }

Precision Rounding

Rounding to specified decimal places...	{ "stats": { "raw_value": 123.45678 } } - math: field: stats.rounded operation: round left_operand: "stats.raw_value" precision: 2
rounds to two decimal places:	{ "stats": { "raw_value": 123.45678, "rounded": 123.46 } }

Complex

Combining operations in a pipeline...	{ "circle": { "radius": 5 } } - math: field: circle.radius_squared operation: pow left_operand: "circle.radius" right_operand: "2" - math: field: circle.area operation: multiply left_operand: "circle.radius_squared" right_operand: "3.14159" precision: 2
calculates area in multiple steps:	{ "circle": { "radius": 5, "radius_squared": 25, "area": 78.54 } }

Error Handling

Handling potential calculation errors...	{ "stats": { "numerator": 100, "denominator": 0 } } - math: field: stats.result operation: divide left_operand: "stats.numerator" right_operand: "stats.denominator" on_failure: - set: field: stats.error value: "Division by zero error" - set: field: stats.result value: 0
continues execution:	{ "stats": { "numerator": 100, "denominator": 0, "error": "Division by zero error", "result": 0 } }