Field Modifiers
Modifiers transform a field value in a format string: {FIELD|modifier}.
The fields of a filter expression are format strings too, so modifiers work there as well.
Separate several modifiers with |, in the order they should run.
An unknown modifier is ignored.
Put escape modifiers last, after all other modifiers: {MESSAGE|70|EscCMD}.
RECEIVED fields take only a date/time format (%Y, %F, …), not the modifiers on this page; see Date/Time Modifiers.
Modifiers at a Glance
| Modifier | Goal |
|---|---|
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 |
|
Safe embedding in SQL, CSV, JSON, a URL, etc. |
Length Limit
To shorten a value, add a number: {MESSAGE|80} keeps the first 80 bytes.
The limit counts bytes, not characters.
If {MESSAGE} is Abcdef, {MESSAGE|3} is Abc.
| With non-ASCII text, a limit can cut a character in the middle. |
Use a limit to fit a value into a fixed-size place, such as an email subject or a database column. In a filter expression, it also speeds up a search when the text you look for is near the start of the message.
{MESSAGE} CONTAINS "keyword"
{MESSAGE|50} CONTAINS "keyword" (scans only the first 50 bytes)
Substring
A modifier with # takes part of the value.
Offsets count bytes and start at 0.
| 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.
Without #, a number is a length limit, not a substring: {MESSAGE|3} is Abc.
| A substring has the same uses as a length limit: fitting a value into a fixed-size place, or searching only part of the message in a filter. It also counts bytes, so with non-ASCII text it can cut a character in the middle. |
UPPER / lower
UPPER and lower change letter case.
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, and LOGIN.
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 an empty header field, so {PROCID|?-} is a typical use.
Regular Expression
The modifier r/ pattern / transforms the value with a regular expression.
The result is the text of all capturing groups joined together; it is empty when the pattern does not match or has no groups.
An invalid pattern is ignored; it does not affect the rest of the format string.
If {FIELD} is AB-123-CD, {FIELD|r/-([0-9]+)-/} is 123.
For better performance, search only part of the message by putting a length limit or substring first: {MESSAGE|32|r/%ASA-\d+-(\d+)/}.
Field Dictionary
FD: name and FDX: name look up the value in a field dictionary; see Use a Dictionary.
KB: and KBX: (from Syslog Watcher 6) work the same as FD: and FDX:.
|