Routers
What are Routers?
With routers, you can perform complex matching and actions on alerts. Routers consist of many router rules that are processed after the integration has transformed the 3rd party data into an alert, but before the alert has been assigned to the team.
Routers are objects that can dynamically route alerts based on match conditions.
Alerts are sent to a router either by an Integration or Account User.
To access routers, you must enable "advanced mode".
Router rules are evaluated in top down order.
If no rules are matched, alerts are routed to the default receiver.
Routers are written in YAML.
Routers Video
Rules Syntax
rules - array - Always the root element - 1..n
match - hash - 1 match condition (object) - 1
actions - array - 1 or more actions to perform - 1..n
Match Block
The match block will attempt to match data using operators.
Data
When routers are matching rules they are given access to data.
Operators
Internally PagerTree uses the sift package to do rule matching. It follows the familiar MongoDB syntax.
There are 3 special functions that are supplemental.
$day
Returns - ISO day of the week (1 Monday, 7 Sunday): integer.
Parameters
timezone - A valid momentjs timezone, default: Etc/UTC
$now
Returns - Current datetime in the specified format: string.
Parameters
timezone - A valid momentjs timezone, default: Etc/UTC
format - A valid momentjs string formats, default: YYYY-MM-DD
$timeBetween
Returns - A boolean if the current time is between (inclusive) the time provided :boolean
Parameters
timezone - A valid momentjs timezone, default: Etc/UTC
timeformat - A valid momentjs string formats, default: "hh:mm a"
starttime - The start time to consider.
endtime - The end time to consider.
Note: If the start time is after the end time, this simulates checking the over night time span.
Actions Block
Action Types
aggregate - Aggregate alerts based on fields.
assign - Assign the alert to a team, router, or account user.
ignore - Suppress the alert.
incident - Mark the alert as an incident.
setval - Set a value on the alert.
stakeholder - Attach a stakeholder to the alert.
Aggregate
The aggregate function will aggregate alerts by the specified by properties for timeout amount of time. The first alert will be immediately routed to the receiver and all subsequent alerts that arrive matching the aggregate by will be added as a child to the first alert and immediately discarded.
Parameters
by - array - properties to generate a fingerprint from
timeout - string - ms notation of the duration to aggregate alerts for.
receiver - string - account user, router, or team Prefix ID to route the initial alert to.
Assign
The assign function will assign the alert to an account user, router or team.
Parameters
receiver - string|array - account user, router, or team Prefix ID to route the alert to.
delay - string - ms notation of the duration to delay the initial routing. (Useful if alerts tend to self heal)
Ignore
The ignore function will change the alert's status to suppressed
and stop routing.
Incident
The incident action will mark the alert as an incident.
Parameters
severity - string - A valid severity level of the incident (SEV-1|SEV-2|SEV-3|SEV-4|SEV-5|SEV-UNKNOWN)
message - string - The special incident message that will be displayed at the top of the alert page.
handlebars - boolean - Boolean indicating severity and message should use handlebars notation.
Setval
The setval action will assign data to the alert. Define a custom title, description, tags, or urgency.
Parameters
map - hash - Allowed keys: title, description, tags, and/or urgency.
handlebars - boolean - Boolean indicating severity and message should use handlebars notation.
Stakeholder
The stakeholder action will attach stakeholders to the alert.
Parameters
ids - array - Stakeholder Prefix IDs
Putting It All Together
Attach the Router to your Integration
When you are happy with your router definition you must connect the Integration to the Router.
For each integration that should use your routers logic:
Edit the Integration
Change the Destinations to be your new router
Click Save
Examples
Example #1 Always Aggregate By Source
Matches everything
Aggregates by unique alert.source_id (usually a integration or user) for a period of 1 hour
Assigns the alert to team tem_xxxxxx1
Example #2 Critical System Down Router
Matches any alert with "Critical Systems Down" (case insensitive) in the title and the urgency of high or critical.
Attaches stakeholder stk_xxxxx1 to the alert.
Assigns the alert to team tem_xxxxxx1 with 5 minute delay to allow for self healing.
Example #3 Aggregate by Title
Matches any alert with "staging" (case sensitive) in the title.
Aggregates by unique alert.title for a period of 1 day.
The first occurrence of each unique title will be routed to tem_xxxxxx1.
Example #4 Office Hours
Matches current time of day between 8a-5p, M-F (Europe/London) and routes to tem_xxxxxx1.
If outside of office hours, the alert is ignored.
This router makes use of the $and
, $timeBetween
, $day
and $in
operators.
Common Errors
Routers are some of the most complex pieces of PagerTree. If you run into issues make sure to check out the Router Workflows and their logs.
Forgot to Set Integration Destination
Many times a customer has written the router correctly but forgets to set the integration destination as the router.
Don't forget to point the integrations that should use the router logic to point to your router!
Bad Indentation
A common error when configuring routers is that the YAML is not formatted correctly (mostly always indentation). You can use the JSON2YAML tool to check your indentation.
Last updated