Document toolboxDocument toolbox

Using regex in relay rules

The more sophisticated relay rules use the information contained within the inbound Syslog event to identify, classify, and process the event. 

This is when regular expressions, or regex, come in very handy. A regex is a sequence of characters that define a search pattern. The regex sequence can define capturing groups or parts of the pattern that you want to be able to reference. A capturing group is identified by enclosing the relevant part of the regex pattern in parenthesis and referenced using the Devo backreferences described in this article. The regex is applied to text with the goal of identifying matching patterns. When a match is found, it then becomes possible to validate, identify, or replace key information. 

Read more about regular expressions in Wikipedia.

In the case of a relay rule, regex can be used in the Source message, Source data, or Source tag fields of the rule editor to reflect patterns expected in the inbound events. In these patterns, capturing groups can be employed to identify key source values that can be backreferenced for event rule processing. For example, when you want to use a Syslog message component to form part of the Devo tag. To do this, you need to use a Devo backreference.

Devo backreferences

Capturing groups set in regex in the Source message, Source data or Source tag fields can be referenced from the Target tag and Target message fields using a syntax created by Devo and based upon standard backreferences in regex. 

Devo backreference

Scope

Devo backreference

Scope

\\mX

Use this syntax to capture groups set in the Source message field.

\\dX

Use this syntax to capture groups set in the Source data field.

\\pX

Use this syntax to capture groups set in the Source tag field.

  • Replace the X by the number of the group you want to capture. For example, use \\d1 to match the first capturing group in the regex specified in the Source data field.

  • Replace the X by a 0 to match the entire component as it was received by the relay. For example, use \\m0 to match the entire Source message field.

A typical regex use case

A common use of regex in a relay rule is when you need to use data contained in the inbound event to build levels of the event source's tags. For example, let's say we have a data source that generates a few different types of events, and each event should be assigned a tag where the event type is the third level of the tag. Like this: technology.brand.eventtype

This data source generates events using a pattern where the event type is described by the string that sits between the third and fourth commas in the event. In this case, the following regex, which is entered in the Source message field, accurately describes the beginning of the event, sets the event type value as a capturing group, then essentially ignores whatever happens after the event type until the end of the event.

^[^,]+,[^,]+,[^,]+,([^,]+).*$

In order to reference the capturing group from the Target tag field, we use the Devo backreference  \\m1

This rule example is just a placeholder but there are several examples of actual Devo tags that work this way. You can have a look at Scenario 4: Assign dynamic Devo tag using inbound source data further illustration of this use of regex and Devo backreferences.