Overview
The formula (or expression) defines the value of the value of the calculated field for each log event. You can reference log attributes, other calculated fields, and supported functions and operators. As you write or edit a formula, the editor automatically suggests relevant fields, functions, and operators.
Basic syntax and language constructs
| Construct | Syntax and Notation |
|---|
Reserved attribute or tag named tag | tag (no prefix required)
For tags containing dashes, escape them with a backslash.
Example: ci\-job\-id |
Attribute named attr | @attr (use an @ prefix) |
Calculated field named field | #field (use a # prefix) |
String literal (quote)
For example, text or Quoted "text". | "text"
"Quoted \"text\""
(Log Search Syntax applies) |
Numeric literal (number)
For example, ten. | 10 |
Function named func with parameters x and y | func(x, y) |
Operator
For example, a binary operator * with operands x and y. | x*y |
Operators
The available operators in order of precedence:
| Operator | Description |
|---|
() | A grouping or function call |
!, NOT, - | A logical or arithmetic negation |
^, % | Exponentiation, Modulo |
*, / | Multiplication, division |
+, - | Addition, subtraction |
<, <=, >, >= | Less than, less than or equal to, greater than, greater than or equal to |
==, != | Match, does not match |
&&, AND | Logical AND |
||, OR | Logical OR |
Functions
The available functions are categorized as follows:
Arithmetic
abs(num value)
Returns the absolute value of a number.
| Example | Formula | Result |
|---|
A log event has the following attributes:
- @client_latency = 2
- @server_latency = 3 | #discrepancy = abs(@client_latency - @server_latency) | #discrepancy = 1 |
ceil(num value)
Rounds number up to the nearest integer.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@value = 2.2 | #rounded_up = ceil(@value) | #rounded_up = 3 |
floor(num value)
Rounds number down to the nearest integer.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@value = 9.99 | #rounded_down = floor(@value) | #rounded_down = 9 |
max(num value, [ num value, …])
Finds maximum value amongst a set of numbers.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@CPU_temperatures = [-1, 1, 5, 5] | #highest_temp = max(@CPU_temperatures) | #highest_temp = 5 |
min(num value, [num value, …])
Finds the minimum value amongst a set of numbers.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@CPU_temperatures = [-1, 1, 5, 5] | #lowest_temp = min(@CPU_temperatures) | #lowest_temp = -1 |
round(num value, int precision)
Rounds a number. Optionally, define how many decimal places to maintain.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@value = -1234.01 | #rounded_to_tens = round(@value, -1) | #rounded_to_tens = -1230 |
String
concat(str string [str string, expr value, …])
Combines multiple values into a single string.
| Example | Formula | Result |
|---|
A log event has the following attributes:
- @city = “Paris”
- @country = “France” | #region = concat(@city, ", ", @country) | #region = “Paris, France” |
lower(str string)
Converts string to lowercase.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@first_name = “Bob” | #lower_name = lower(@first_name) | #lower_name = “bob” |
left(str string, int num_chars)
Extracts a portion of text from the beginning of a string.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@price = “USD10.50” | #currency = left(@price, 3) | #currency = “USD” |
proper(str string)
Converts string to proper case.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@address = “123 main st” | #formatted_address = proper(@address) | #formatted_address = “123 Main St” |
split_before(str string, str separator, int occurrence)
Extracts the portion of text preceding a certain pattern in a string.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@url = "www.example.com/path/to/split" | #url_extraction = split_before(@url, "/", 1) | #url_extraction = "www.example.com/path" |
#url_extraction = split_before(@url, "/", 2) | #url_extraction = "www.example.com/path/to" |
split_after(str string, str separator, int occurrence)
Extracts the portion of text following a certain pattern in a string.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@url = "www.example.com/path/to/split" | #url_extraction = split_after(@url, "/", 0) | #url_extraction = "path/to/split" |
#url_extraction = split_after(@url, "/", 1) | #url_extraction = "to/split" |
substring(str string, int start, int length)
Extracts a portion of text from the middle of a string.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@price = “USD10.50” | #dollar_value = substring(@price, 2, 2) | #dollar_value = “10” |
right(str string, int num_chars)
Extracts a portion of text from the end of a string.
| Example | Formula | Result |
|---|
A log event has the following attribute:
@price = “USD10.50” | #cent_value = right(@price, 2) | #cent_value = “50” |
textjoin(str delimiter, bool ignore_empty, str string [str string, expr value, …])
Combines multiple values into a single string with a delimiter in between.
| Example | Formula | Result |
|---|
A log event has the following attributes:
- @city = “Paris”
- @country = “France” | #region = textjoin(", ", "false", @city, @country) | #region = “Paris, France” |
upper(str string)
Converts string to uppercase.
| Example | Formula | Result |
|---|
A log event has the following attribute: @first_name = “Bob” | #upper_name = upper(@first_name) | #upper_name = “BOB” |
Logical
if(expr condition, expr if_true, expr if_false)
Evaluates a condition and returns a value accordingly.
| Example | Formula | Result |
|---|
A log event has the following attributes:
- @location = “Paris, France”
- @home = “New York, USA” | #abroad = if(@location == @home, "false", "true") | #abroad = “true” |
is_null(expr value)
Checks if an attribute or expression is null.
| Example | Formula | Result |
|---|
A log event has the following attributes:
- @users_online = 5
- @max_capacity = 0 | is_null(@users_online / @max_capacity) | “true” |
Regex
Regex functions match or transform a value using a regular expression (regex). Patterns support the same regex constructs as regex extraction, such as literals, character classes, and quantifiers. The same pattern performance guidance applies. Unlike extraction, capture groups in formula patterns do not need a name.
Formula arguments are double-quoted string literals, so a literal backslash must be written as two backslashes. For example, to match the digit shorthand class, write "\\d" in the pattern. The same rule applies to the replacement string: to insert a literal dollar sign rather than a group reference, write "\\$".
regexp_like(str value, str pattern)
Returns true when the pattern matches anywhere in the value, and false otherwise.
| Example | Formula | Result |
|---|
A log event has the following attribute:
message = “connection timeout after 30s” | #is_timeout = regexp_like(message, "timeout|deadline exceeded") | #is_timeout = “true” |
regexp_replace(str input, str pattern, str replacement, [int start, int N])
Returns input with matched text replaced. Use $1 through $9 in replacement to insert a capture group’s match, or ${name} for a named group.
| Argument | Meaning |
|---|
input | The text to transform |
pattern | The regex pattern to match |
replacement | The regex transformation pattern, often using capture groups |
start | Optional. The zero-based character index to begin matching from. Defaults to 0 |
N | Optional. The maximum number of matches to replace. Defaults to 1. 0 replaces every match |
| Example | Formula | Result |
|---|
A log event has the following attribute:
@path = “/api/v1/orders” | #resource = regexp_replace(@path, "^/api/v[0-9]+/(.*)$", "$1") | #resource = “orders” |
Further reading
Additional helpful documentation, links, and articles:
