Field Modifiers
Modifiers transform a field value in a format string or a filter expression.
Separate several modifiers with |, in the order they should run.
Put escape modifiers last so the escaped form is what the destination sees: {MESSAGE|70|EscCMD}.
Date and time patterns (%Y, %F, …) apply only to RECEIVED fields — see Date/Time Modifiers.
Which Modifier
| Goal | Modifier |
|---|---|
First N bytes |
|
Last N bytes |
|
From byte offset N to the end |
|
M bytes from offset N |
|
Letter case |
|
Replacement when the field is empty |
|
Extract with a regular expression |
|
Look up text in a Field Dictionary |
|
Look up a format string in a Field Dictionary |
|
Date or time layout ( |
|
Safe embedding in SQL, CSV, JSON, a URL, or a command line |
Length Limit
A number as a modifier keeps the first N bytes (not characters). That matters for non-ASCII encodings.
If {MESSAGE} is Abcdef, {MESSAGE|3} is Abc.
A length limit is useful for export width and for filter performance when the interesting text is near the start of the body.
{MESSAGE} CONTAINS "keyword"
{MESSAGE|50} CONTAINS "keyword" (scans only the first 50 bytes)
Substring
A modifier that contains # takes a slice of the value, in bytes, with a 0-based offset.
| Form | Result |
|---|---|
|
Last N bytes. |
|
From offset N to the end. |
|
M bytes starting at offset N. |
|
Empty. |
If {MESSAGE} is Abcdef:
{MESSAGE|#3} is def.
{MESSAGE|2#} is cdef.
{MESSAGE|1#2} is bc.
|{3} (no #) is still a length limit — the first 3 bytes — not a substring.
UPPER / lower
UPPER and lower change letter case.
ASCII letters are converted first; any remaining UTF-8 text is converted as a unit.
If {MESSAGE} is Abc, {MESSAGE|UPPER} is ABC.
If {MESSAGE} is Abc, {MESSAGE|lower} is abc.
Use either modifier for a case-insensitive filter comparison.
{MESSAGE|lower} CONTAINS "login" matches login, Login, LOGIN.
{MESSAGE|50|lower} CONTAINS "login" when the keyword is near the start.
Blank Field Filler
A modifier that starts with ? supplies replacement text when the field is empty.
? with no text after it is ignored.
If {MESSAGE} is Abc, {MESSAGE|?Blank} is Abc.
If {MESSAGE} is empty, {MESSAGE|?Blank} is Blank.
RFC 5424 uses - for a missing structured field; {PROCID|?-} is a typical filler.
Regular Expression
The modifier r/ pattern / transforms the value with a regular expression.
The result is the concatenation of all capturing groups (a pattern with no groups yields an empty value).
| may appear inside the pattern.
An invalid pattern is skipped and the rest of the template still prints.
If {FIELD} is AB-123-CD, {FIELD|r/-([0-9])-/}+ is 123.
A length limit before the regex reduces how much of the body is scanned: {MESSAGE|32|r/%ASA-\d-(\d+)/}+.
See Fields for using this modifier to build extra names from {MESSAGE}.
Field Dictionary
FD: name looks up the current field value as a key in the Field Dictionary named name and replaces the value with the matching text.
If the key is missing, the dictionary default is used (empty when the dictionary has no default).
FDX: name does the same lookup, then treats the dictionary text as a format string and prints it (the entry may include other fields).
KB: and KBX: are the same modifiers as FD: and FDX:.