Escalation policies make sure the right people are notified at the right time and is the connector between services and schedules — a service can only have one escalation policy, though an escalation policy can be associated with multiple services.
Escalation policies are found under Configuration → Escalation Policies, where there will already be a Default escalation policy. By default, the Account Owner will be the only target on this escalation policy, though this can be changed at any time.
To create an escalation policy:
- Go to Configuration → Escalation Policies.
- Click New Escalation Policy.
- Name your escalation policy and optionally add a description.
- Select the targets (on-call schedules and/or users) you want to notify immediately after an incident is triggered.
- If you would like to add a second level to the escalation policy, choose the number of minutes that should pass, without receiving an acknowledge or resolution, before the incident escalates (escalation timeout).
- Then click Add a new Escalation Rule to create the second level.
- Select targets for the second escalation rule.
- Configure additional escalation rules as required.
- When finished, click Save.
Check the box next to If no one acknowledges, repeat this policy __ and select the number of times to loop through the escalation policy (maximum is 9 times).
In the example below, if an on-call user in the Primary On-Call Schedule schedule does not acknowledge an incident in 30 minutes, then it will escalate to Jason Collison. The escalation timeout at the second level is also 30 minutes, and Jason will have 30 minutes to acknowledge the incident before it escalates and starts over from the beginning of the policy. This escalation policy is set up to repeat 9 times.
You can select users or schedules as targets on an escalation policy. When an incident triggers, we'll attempt to notify responders at the first level of the escalation policy. If the incident is not acknowledged within the escalation timeout period, then it will escalate to the on-call responders at the next escalation level, and so on down the line.
If nobody is on-call in the first level, then we will assign the incident to the on-call responder at the subsequent escalation level.
An incident follows the escalation policy as it was at the time the incident triggered. This means that if changes are made to an escalation policy, these changes will not affect any open (triggered or acknowledged) incidents associated with that escalation policy.
- You can add up to 20 escalation rules to an escalation policy.
- You have the option to repeat an escalation policy 9 times. Once an escalation policy reaches the amount of loops configured, the incident will stay assigned to the last user and will not continue to notify once it has cycled through all of the responder's contact methods.
- You can notify up to 10 users/schedules (25 on Standard and Enterprise plans) in a single escalation rule.
- The minimum escalation timeout is 1 minute if there is a single target on an escalation rule. Alternatively, if there is more than one target in an escalation level the minimum escalation timeout is 5 minutes. These restrictions are displayed in the web UI.
Multi-user notifications will notify multiple users at once when an incident is triggered or escalated, and can be configured within an escalation policy. To notify 2 or more users at once, you will want to configure an escalation policy so that multiple on-call schedules and/or users are in the same escalation level.
An important concept to grasp is that only one user can be on-call per schedule. A natural first instinct would be to add multiple layers to a schedule, however the way PagerDuty's system works, the lowest layer on a schedule takes precedence over any others.
The following screenshot demonstrates what will happen if multiple layers are stacked on top of each other (Layer 3 takes precedence over Layers 1 and 2):
To notify 2 or more users at once, you will want to set up an escalation policy with multiple on-call schedules/users on the same escalation level.
Go to Configuration > Escalation Policies.
Click New Escalation Policy to create a new escalation policy, or click an existing escalation policy's gear icon and then Edit to edit an existing one.
Click in the field below Notify the following users or schedules and select the on-call schedules and/or users you want to notify when an incident is triggered or escalated.
Click Save and you're done!
If you have Live Call Routing enabled to connect directly, PagerDuty will not call all users on an escalation level — only one user per escalation level will receive a call. If an incident triggers via Live Call Routing (if either no one answers, or you've selected "Leave a Message"), however, all users on an escalation level can expect to receive notifications via their configured notification methods.
Select a user if you always want that specific user to be notified when an incident is assigned and/or escalated to an escalation level.
Select an on-call schedule if you only want to notify the user from that schedule who happens to be on-call when an incident triggers.
Notifying too many users at once runs the risk of creating confusion about who owns an incident. With this is mind, multi-user notifications are limited to 25 users or schedules on Standard and Enterprise plans and 10 users or schedules on Lite and Basic plans.
This topic addresses best practices about when to notify one user vs. many users.