FilterX operator reference

This page describes the operators you can use in FilterX blocks.

Comparison operators

Comparison operators allow you to compare values of macros, variables, and expressions as numbers (==, <, <=, >=, >, !=) or as strings (eq, lt, le, gt, ge, ne). You can also check for type equality (===) and strict inequality (!==). For details and examples, see Comparing values in FilterX.

Boolean operators

The not, or, and operators allow you to combine any number of comparisons and expressions. For details and examples, see Boolean operators in FilterX.

Assign if non-null (=??) operator

Available in AxoSyslog 4.10 and later.

Assigns the right operand to the left operand if the right operand is not null. Note that evaluation errors of the right-hand operand will be suppressed.

left-operand =?? right-operand

For example:

`resource.attributes['service.name'] =?? $PROGRAM;`

Using the =?? operator is equivalent to the following expression, but using =?? has better performance.

if (isset($PROGRAM) ?? false) {
    resource.attributes['service.name'] = $PROGRAM;
};

## Null coalescing operator

The [null coalescing operator](https://en.wikipedia.org/wiki/Null_coalescing_operator) returns the result of the left operand if it exists and is not null, otherwise it returns the operand on the right.

```shell
left-operand ?? right-operand

You can use it to define a default value, or to handle errors in your FilterX statements: if evaluating the left-side operand returns an error, the right-side operand is evaluated instead.

For example, if a key of a JSON object doesn’t exist for every message, you can set it to a default value:

${MESSAGE} = json["BODY"] ?? "Empty message"

Plus operator

The plus operator (+) adds two arguments, if possible. (For example, you can’t add two datetime values.)

• You can use it to add two numbers (two integers, two double values). If you add a double to an integer, the result is a double.

• Adding two strings concatenates the strings. Note that if you want to have spaces between the added elements, you have to add them manually, like in Python, for example:

  ${MESSAGE} = ${HOST} + " first part of the message," + " second part of the message" + "\n";
  

• Adding two lists merges the lists. Available in AxoSyslog 4.9 and later.

• Adding two dicts updates the dict with the values of the second operand. For example:

  x = {"key1": "value1", "key2": "value1"};
  y = {"key3": "value1", "key2": "value2"};
  ${MESSAGE} = x + y; # ${MESSAGE} value is {"key1": "value1", "key3": "value1", "key2": "value2"};
  

  Available in AxoSyslog 4.9 and later.

Plus equal operator

The += operator increases the value of a variable with the value on the right. Exactly how the addition happens depends on the type of the variable.

• For numeric types (int and double), the result is the sum of the values. For example:

  a = 3;
  a += 4;
  # a is 7
  
  b = 3.3;
  b += 4.1;
  # b is 7.4
  

  Adding a double value to an integer changes the integer into a double:

  c = 3;
  c += 4.1;
  # c is 7.1 and becomes a double
  

• For strings (including string values in an object), it concatenates the strings. For example:

  mystring = "axo";
  mystring += "flow";
  # mystring is axoflow
  

• For lists, it appends the new values to the list. For example:

  mylist = json_array(["one", "two"]);
  mylist += ["let's", "go"];
  # mylist is ["one", "two", "let's", "go"]
  

• For datetime variables, it increments the time. Note that you can add only integer and double values to a datetime, and:

  • When adding an integer, it must be the number of microseconds you want to add. For example:

    d = strptime("2000-01-01T00:00:00Z", "%Y-%m-%dT%H:%M:%S%z");
    d += 3600000000; # 1 hour in microseconds
    # d is "2000-01-01T01:00:00.000+00:00"
    

  • When adding a double, the integer part must be the number of seconds you want to add. For example:

    d = strptime("2000-01-01T00:00:00Z", "%Y-%m-%dT%H:%M:%S%z");
    d += 3600.000; # 3600 seconds, 1 hour
    # d is "2000-01-01T01:00:00.000+00:00"
    

Regexp match (equal tilde)

To check if a value contains a string or matches a regular expression, use the =~ operator. For example, the following statement is true if the ${MESSAGE} contains the word error:

${MESSAGE} =~ "error";

Use the !~ operator to check if a literal string or variable doesn’t contain an expression. For example, the following statement is true if the ${MESSAGE} doesn’t contain the word error:

${MESSAGE} !~ "error";

Note the following points:

• Regular expressions are case sensitive by default. For case insensitive matches, add (?i) to the beginning of your pattern.
• You can use regexp constants (slash-enclosed regexps) within FilterX blocks to simplify escaping special characters, for example, /^beginning and end$/.
• FilterX regular expressions are interpreted in “leave the backslash alone mode”, meaning that a backslash in a string before something that doesn’t need to be escaped and will be interpreted as a literal backslash character. For example, string\more-string is equivalent to string\\more-string.

Ternary conditional operator

The ternary conditional operator evaluates an expression and returns the first argument if the expression is true, and the second argument if it’s false.

Syntax:

<expression> ? <return-if-true> : <return-if-false>

For example, the following example checks the value of the ${LEVEL_NUM} macro and returns low if it’s lower than 5, high otherwise.

(${LEVEL_NUM} < 5 ) ? "low" : "high";

You can also use it to check if a value is set, and set it to a default value if it isn’t, but for this use case we recommend using the Null coalescing operator:

${HOST} = isset(${HOST}) ? ${HOST} : "default-hostname"