Regular Expressions

Regular expressions (regex) are a standard, well-documented way to match and extract text. In the context of Event Orchestrations, you can use regex to determine event routing rules as well as in Dynamic Field Enrichment & Extraction. In the context of PagerDuty email integrations, you can use regex to fine-tune your email filters and email management rules.

Use Regex to Extract an Incident/Alert Key

If you use a regular expression to extract the incident/alert key of an email event, you will need to use a capture group. In regex, a capture group is defined as anything between a set of parentheses, (... ).

Capture Group

A capture group will tell PagerDuty to create an incident/alert key from the text between a set of parentheses, (...). If the unique identifier within the capture group is likely to change (e.g., a numeric string like a ticket ID or host ID), you can use \d+, which tells PagerDuty to capture all subsequent digits.

Similarly, if you want to capture a specific number of digits you could use \d to stand in place of each digit. For example, you could use \d\d\d\d or \d{4} if the unique identifier always contains 4 digits.

Capture Parentheses in the Unique Identifier

In some instances your unique identifier may contain parentheses. For example, Zendesk ticket IDs typically contain parentheses: This ticket (#27415) has been assigned to group ‘Support’, of which you are a member.

To capture the parentheses in a regex, use a backslash (\) before each parenthesis, for example: \(#\d+\). The backslash acts as an escape character that tells PagerDuty "the following character should be treated as text."

HTML Emails and Content Encoding

Email management regular expressions are compared on the text of the email after decoding, per the encoding specified by Content-Transfer-Encoding. However, Content-Type is ignored. In other words, if, after decoding a base64-encoded email, the underlying message is HTML, and there is no plain text copy of the email included, then the regular expression will run on the HTML code, not on the text that would result after rendering the HTML or stripping out HTML tags.

This means that if emails are sent only as HTML (Content-Type: text/html), regular expressions written to match the text content alone may not work. HTML tags, hidden line breaks, and whitespace can potentially interfere with your regular expressions’ ability to match the input.

See Troubleshooting for further details.

Case Sensitivity

Regular expressions are case sensitive, so "DOWN", "down", and "Down" are all considered different strings and will not all match against the same regex. You can make your email management rules case insensitive by adding (?i) to the beginning of the line, for example: (?i)(critical)

This will capture all cases: "critical", "CRITICAL", "cRiTicAL", etc.

👍

Tip

The case insensitivity modifier (?i) works in email management rules, however it is not supported with email filters. With this in mind, we suggest using a pipe character (|) to capture different upper/lowercase strings for email filters, for example: (Down|DOWN|down)

Test Your Regex

We recommend Regex101 to compose, edit and test your regular expressions.

To test a regular expression in Regex101, enter your test string (in this example, you’d like to extract the node, A74U-138, from the email body and use it as the incident/alert key) and make sure that the regex show a Group 1 match.

👍

Regex Testing Tip

When using the external site Regex101 to test your regex, please select the following options:

• Golang flavor
• multi line
• single line

If your regular expression matches on the sample text you enter into Regex101, it should work for the same text in PagerDuty.

Specifics of PagerDuty's Capture Group Implementation

PagerDuty's email management rules use Google's RE2 for regular expression handling, and additionally adds some custom behavior. Some specific things to be aware of:

• Nested capture groups are not supported. The following regular expression will generate an error when saving the service: (([0-9])[0-9]).
• If you define multiple capture groups, we will concatenate what is captured in each group together, using a - character. For example, if you match ([a-z])([a-z]) against ab, PagerDuty will extract this as a-b.
• Two options are always added to your regular expression (documented in the RE2 documentation) when extracting data:
  • s (single-line mode) means that the . special character will also match newlines (\n).
  • m (multi-line mode) causes ^ and $ to match the beginning and end of lines, in addition to beginning and end of the entire text.
  • A consequence of these two behaviors and regex greediness is that (.*)$ will match everything until the end of the document. We recommend using ([^\n]*) if you’d like to match everything until the end of the line.

Regex Examples

Here is an example of a common use case using a regular expression:

Your PagerDuty service receives emails from a monitoring tool, however you only want to trigger incidents if the subject line starts with “CRITICAL” or “SEVERE”. The regular expression you would use to match incidents of this type would be: ^(CRITICAL|SEVERE).

The ^ character means the subject line starts with this, and (CRITICAL|SEVERE) means the starting word can be either "CRITICAL" or "SEVERE".

Other Common Regex Examples