Routers
Last updated
Last updated
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.
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
The match block will attempt to match data using operators.
When routers are matching rules they are given access to data.
Internally PagerTree uses the sift package to do rule matching. It follows the familiar MongoDB syntax.
There are 3 special functions that are supplemental.
Returns - ISO day of the week (1 Monday, 7 Sunday): integer.
Parameters
timezone - A valid momentjs timezone, default: Etc/UTC
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
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.
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.
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.
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)
The ignore function will change the alert's status to suppressed and stop routing.
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.
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.
The stakeholder action will attach stakeholders to the alert.
Parameters
ids - array - Stakeholder Prefix IDs
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
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
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.
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.
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.
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.
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!
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.
