Variable (Property) types — rsyslog 8.24.0 documentation

# Variable (Property) types

All rsyslog properties (see the property replacer page for a list) can be used in RainerScript. In addition, it also supports local variables. Local variables are local to the current message, but are NOT message properties (e.g. the “$!” all JSON property does not contain them).

Only message json (CEE/Lumberjack) properties can be modified by the set, unset and reset statements, not any other message property. Obviously, local variables are also modifieable.

Message JSON property names start with “$!” where the bang character represents the root.

Local variables names start with “$.”, where the dot denotes the root.

Both JSON properties as well as local variables may contain an arbitrary deep path before the final element. The bang character is always used as path separator, no matter if it is a message property or a local variable. For example “$!path1!path2!varname” is a three-level deep message property where as the very similar looking “$.path1!path2!varname” specifies a three-level deep local variable. The bang or dot character immediately following the dollar sign is used by rsyslog to separate the different types.

Check the following usage examples to understand how these statements behave:

## set

sets the value of a local-variable or json property, but the addressed variable already contains a value its behaviour differs as follows:

merges the value if both existing and new value are objects, but merges the new value to root rather than with value of the given key. Eg.

    set $.x!one = "val_1";
    # results in $. = { "x": { "one": "val_1" } }
    set $.y!two = "val_2";
    # results in $. = { "x": { "one": "val_1" }, "y": { "two": "val_2" } }

    set $.z!var = $.x;
    # results in $. = { "x": { "one": "val_1" }, "y": { "two": "val_2" }, "z": { "var": { "one": "val_1" } } }

    set $.z!var = $.y;
    # results in $. = { "x": { "one": "val_1" }, "y": { "two": "val_2" }, "z": { "var": { "one": "val_1" } }, "two": "val_2" }
    # note that the key *two* is at root level and not  under *$.z!var*.

ignores the new value if old value was an object, but new value is a not an object (Eg. string, number etc). Eg:

    set $.x!one = "val_1";
    set $.x = "quux";
    # results in $. = { "x": { "one": "val_1" } }
    # note that "quux" was ignored

resets variable, if old value was not an object.

    set $.x!val = "val_1";
    set $.x!val = "quux";
    # results in $. = { "x": { "val": "quux" } }

## unset

removes the key. Eg:

    set $.x!val = "val_1";
    unset $.x!val;
    # results in $. = { "x": { } }

## reset

force sets the new value regardless of what the variable originally contained or if it was even set. Eg.

    # to contrast with the set example above, here is how results would look with reset
    set $.x!one = "val_1";
    set $.y!two = "val_2";
    set $.z!var = $.x;
    # results in $. = { "x": { "one": "val_1" }, "y": { "two": "val_2" }, "z": { "var": { "one": "val_1" } } }
    # 'set' or 'reset' can be used interchangably above(3 lines), they both have the same behaviour, as variable doesn't have an existing value

    reset $.z!var = $.y;
    # results in $. = { "x": { "one": "val_1" }, "y": { "two": "val_2" }, "z": { "var": { "two": "val_2" } } }
    # note how the value of $.z!var was replaced

    reset $.x = "quux";
    # results in $. = { "x": "quux", "y": { "two": "val_2" }, "z": { "var": { "two": "val_2" } } }