Message Matcher Syntax

The message matcher allows sandboxes to select which messages they want to consume (see Heka Message Structure)

1. Examples

• Type == "test" && Severity == 6
• (Severity == 7 || Payload == "Test Payload") && Type == "test"
• Fields[foo] != "bar"
• Fields[foo][1][0] == "alternate"
• Fields[MyBool] == TRUE
• TRUE
• Fields[created] =~ "^2015"
• Fields[string] =~ "foo.example.com"% -- literal pattern vs "foo%.example%.com"
• Fields[widget] != NIL
• Timestamp >= "2016-05-24T00:00:00Z"
• Timestamp >= 1464048000000000000

2. Relational Operators

• == equals
• != not equals
• > greater than
• >= greater than equals
• < less than
• <= less than equals
• =~ Lua pattern match
• !~ Lua negated pattern match

3. Logical Operators

• Parentheses are used for grouping expressions
• && and (higher precedence)
• || or

4. Boolean

• TRUE
• FALSE

5. Constants

• NIL used to test the existence (!=) or non-existence (==) of optional headers or field variables

6. Message Variables

• All message variables must be on the left hand side of the relational comparison

6.1. String

• Uuid - 16 byte raw binary type 4 UUID (useful for partitioning data)
• Type
• Logger
• Payload
• EnvVersion
• Hostname

6.2. Numeric

• Timestamp - in addition to nanoseconds since the UNIX epoch an RFC3339 string is also accepted e.g., "2016-05-24T21:51:00Z"
• Severity
• Pid

6.3. Fields

• Fields[field_name] - shorthand for Field[field_name][0][0]
• Fields[field_name][field_index] - shorthand for Field[field_name][field_index][0]
• Fields[field_name][field_index][array_index] the indices are restricted to 0-255
• If a field type is mis-match for the relational comparison, false will be returned e.g., Fields[foo] == 6 where "foo" is a string

7. Quoted String

• Single or double quoted strings are allowed
• The maximum string length is 255 bytes

8. Lua Pattern Matching Expression

• Patterns are quoted string values
  • An 'escape' pattern modifier of % is allowed e.g. "foo.bar"% is treated as a literal instead of a pattern and behaves like the 'plain' option on string.find(). If there are no pattern match characters in the string this modifier is set automatically.
• See Lua Patterns
• Capture groups are ignored

9. Additional Restrictions

• Message matchers are restricted to 128 relational comparisons
• A NUL character '\0' is not allowed in a matcher string