PagerDuty

Configuring the integration for PagerDuty

Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

Why use the integration for PagerDuty

PagerDuty is an incident response platform for managing alerts, on-call rotations, and escalation policies. The integration for PagerDuty syncs your PagerDuty services, on-call schedules, escalation policies, and incidents into Cortex, connecting each service's operational data to its ownership and metadata in your software catalog.

Instead of switching tools to answer "who is on call for this service?", you can see current on-call information on an entity's details page, view PagerDuty incidents in its event timeline, and trigger incidents without leaving Cortex. When an incident is triggered, the On-call Assistant notifies users via Slack with runbooks, dependencies, and key information about the affected entity. Because PagerDuty data is available in CQL, you can also create Scorecards that enforce on-call standards at scale and track metrics like mean time to resolution (MTTR) in Eng Intelligence.

Integrating PagerDuty with Cortex allows you to:

• Pull in PagerDuty services, on-call schedules, and escalation policies. The on-call user or team appears in the On-call block on an entity's metadata sidebar, and on the entity's details page under Connections > On-call.

• Trigger incidents in PagerDuty directly from Cortex.

• Automatically surface vital information about entity health and metadata when an incident is triggered, using the On-call Assistant.

• View incidents from PagerDuty in an entity's event timeline.

• View on-call information from PagerDuty on the Engineering homepage.

• Use PagerDuty metrics in Eng Intelligence to gain insight into services, incident response, and more.

• Create Scorecards that track progress and drive alignment on projects involving your on-call schedules and alerts.

Configuring PagerDuty

Prerequisites

1. Users with the Configure Integrations permission can configure PagerDuty.

Step 1: Creating an API key in PagerDuty

1. In PagerDuty, go to Integrations > API Access Keys.

2. Create a PagerDuty API key.

   1. When adding the API key, you have the option to set read or write permissions:

      1. Read-only - Enables Cortex to read any and all data from PagerDuty

         1. If you create an API key with Read-only permissions, and you want to use the On-call Assistant in Slack, you also need to configure a webhook to get the Assistant working.

      2. Write - Allows users to trigger incidents from an entity page in Cortex, and enables the On-call Assistant

3. Copy the API key. Don't skip this step! You'll need the key to complete the setup.

A note about Scoped OAuth apps

If you registered a Scoped OAuth app in PagerDuty, you must also grant the following permissions:

• incident.write to create incidents

• escalation_policies.write to create escalation policies

• schedules.write to create schedules

• services.write to create services

• teams.write to create teams

Step 2: Installing the PagerDuty integration in Cortex

1. From the main sidebar, expand Integrations, then select Configurations.

2. Locate PagerDuty, then click Install. The PagerDuty side panel opens.

3. In the PagerDuty side panel, do the following:

   1. From the Category dropdown, select at least one category that applies to the integration (required).

   2. Under API key, paste the API key you generated in PagerDuty (required).

   3. Optionally, toggle on Read-only API key if you created the key with read-only permissions.

4. Click Test connection. A successful connection means your integration is configured correctly.

5. Click Save.

To modify an existing configuration, see Modifying an integration configuration.