> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the integration for PagerDuty

> How to use the integration for PagerDuty in Cortex

This article explains how to use the integration for PagerDuty. For configuration instructions, see [Configuring the integration for PagerDuty](https://docs.cortex.io/ingesting-data-into-cortex/integrations/pagerduty/using-the-integration-for-pagerduty.md#configuring-pagerduty). For instructions on connecting PagerDuty to entities, see [Connecting entities to PagerDuty](https://docs.cortex.io/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty.md).

After you configure the PagerDuty integration, Cortex surfaces on-call and incident data across the app on:

### Entity pages

View current on-call information in the **On-call** block on an entity's metadata sidebar, and on the entity's details page under **Connections > On-call**.

![On-call information on an entity's details page.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/pagerduty-entity.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=c18325c8fe6cb1184271ce17a8541574)

Select the **Events** tab in an entity's left side panel to view recent events pulled in from PagerDuty.

![The Events page.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/pagerduty-events.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=bed8222438adf143fe95fc163f7ab739)

> [!NOTE]
>
> Escalation policy and service details are hyperlinked to the corresponding pages in your PagerDuty instance.

### Engineering homepage

The PagerDuty integration allows Cortex to pull on-call information into the **My on-calls** block on the Engineering homepage. On-call data from PagerDuty is refreshed every 60 minutes.

![The 'My on-calls' section of the Engineering homepage.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/pagerduty-homepage.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=965869e071b1f1fb575c9e860e4dc3af)

### Eng Intelligence

Cortex also pulls in metrics from PagerDuty for Eng Intelligence, which displays MTTR, incidents opened, and incidents opened per week.

## Other ways to use the integration for PagerDuty

### Retrieving on-call information in Slack

If you have the Slack integration set up, you can ask the AI Assistant for current on-call information. Mention `@Cortex` in a channel or direct message and ask a question like "Who's on call for payments-api?" This works for both services and teams with registered PagerDuty schedules or escalation policies.

For setup and usage details, refer to [Using the AI assistant](https://docs.cortex.io/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant.md#using-the-ai-assistant).

### Creating Scorecard rules and writing CQL queries with the PagerDuty integration

With the PagerDuty integration, you can create Scorecard rules and write CQL queries based on incidents, escalations, and on-call metadata.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> [accordion] Check if on-call is set
>
> Check if entity has a registered service, schedule, or escalation policy. If the service does not have any registrations in its entity descriptor, Cortex searches for PagerDuty services matching the tag defined in the entity's `x-cortex-tag` field.
>
> **Definition** - `oncall (==/!=) null`
>
> **Example**
>
> For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities:
>
> ```
> oncall != null
> ```
>
> This rule passes if an entity has a service, schedule, or escalation policy set.

> [accordion] Forbidden contact methods
>
> Number of users in each entity's escalation policy with missing or forbidden contact methods.
>
> Allowed contact methods:
>
> * "SMS"
> * "PHONE"
> * "EMAIL"
> * "PUSH\_NOTIFICATION"
> * "SLACK"
>
> **Definition** - `oncall.usersWithoutContactMethods(allowed=<allowed>, onlyCurrentOncall=<boolean>).length`
>
> **Example**
>
> For a Scorecard focused on ownership, you can use this expression to make sure users have required contact methods enabled:
>
> ```
> oncall.usersWithoutContactMethods(allowed=["SMS", "PHONE"]).length == 0
> ```
>
> This rule passes if every user in an associated escalation policy has either SMS or phone calls enabled as their contact method.
>
> You can also use this expression in the query builder to find users that lack the required contact method:
>
> ```
> oncall.usersWithoutContactMethods(allowed=["EMAIL"]) > 0
> ```
>
> This query surfaces users without email addresses.
>
> If you want to check only current on-call users, you can use the `onlyCurrentOncall` parameter:
>
> ```
> oncall.usersWithoutContactMethods(allowed=["EMAIL"], onlyCurrentOncall=true) > 0
> ```
>
> When this parameter is set to `false` or omitted, the expression checks all users in the associated escalation policy for the next 3 months.

> [accordion] Incident response analysis
>
> Get detailed [on-call analysis stats](https://developer.pagerduty.com/api-reference/694e92fe4f943-get-aggregated-service-data) for each entity:
>
> * Mean assignment count
> * Mean engaged seconds
> * Mean engaged user count
> * Mean seconds to engage
> * Mean seconds to first ack
> * Mean seconds to mobilize
> * Mean seconds to resolve
> * Total business-hour erruptions
> * Total engaged seconds
> * Total escalation count
> * Total off-hour erruptions
> * Total sleep-hour erruptions
> * Total snoozed seconds
> * Total incident count
> * Up time percent
>
> PagerDuty updates its analytics data once per day, and it can take up to 24 hours before new incidents appear in the analytics API.
>
> **Note that this only works if the entity has a registered PagerDuty service ID or if the PagerDuty service name matches the entity tag.**
>
> **Definition** - `oncall.analysis(lookback = <duration>, priority = <List<String>>)`
>
> **Examples**
>
> PagerDuty analytics can easily be used to craft rules for a DORA metrics Scorecard.
>
> For **mean time to acknowledge**, you can use the `meanSecondsToFirstAck` schema definition:
>
> ```
> oncall.analysis(lookback = duration("P7D"), priority = ["P1", "P2"]).meanSecondsToFirstAck <= 300
> ```
>
> Entities pass this rule if incidents in the last week were acknowledged within 5 minutes.
>
> For **mean time to resolve**, you can use `meanSecondsToResolve` to make sure that incidents were handled within an hour:
>
> ```
> oncall.analysis(lookback = duration("P7D"), priority = ["P1"]).meanSecondsToResolve < 3600
> ```
>
> You can also use this expression to write a rule that checks an entity's change failure rate:
>
> ```
> oncall.analysis(lookback = duration("P7D")).totalIncidentCount == 0
> ```
>
> This rule passes if there weren't any incidents in the last week.

> [accordion] Incidents
>
> Get incident data for each entity:
>
> * Assignee ID
> * Created at
> * Incident ID
> * Last updated
> * Resolved at
> * Service ID
> * Status
>
> **Note that this only works if the entity has a registered PagerDuty service ID or if the PagerDuty service name matches the entity tag.**
>
> **Definition** - `oncall.incidents(lookback = <duration>)`
>
> **Examples**
>
> For a Scorecard focused on service maturity or quality, you can use this expression to check the number of incidents opened in the last month:
>
> ```
> oncall.incidents(lookback = duration("P1M")).length < 15
> ```
>
> Entities pass this rule if they have fewer than 15 incidents opened in the last month.
>
> You can also use this expression to make sure there aren't incidents that remained open over the last month:
>
> ```
> oncall.incidents(lookback=duration("P1M")).filter((incident) => incident.status.matches("TRIGGERED|ACKNOWLEDGED")).length < 1
> ```
>
> Or you can check for incidents that took a certain amount of time to resolve:
>
> ```
> oncall.incidents(lookback=duration("P1M")).filter((incident) => incident.createdAt.until(incident.resolvedAt) > duration("P-2D")).length < 2
> ```
>
> Entities pass this rule if there were 0 or 1 incidents in the last month that took more than 2 days to resolve.

> [accordion] Number of escalations
>
> Number of escalation tiers in escalation policy.
>
> **Definition** - `oncall.numOfEscalations()`
>
> **Example**
>
> This expression could be used in a Scorecard focused on production readiness or service maturity:
>
> ```
> oncall.numOfEscalations() >= 2
> ```
>
> This rule checks that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup.
>
> While making sure an on-call policy set is a rule that would be defined in a Scorecard's first level, a rule focused on escalation tiers would make more sense in a higher level.

> [accordion] On-call metadata
>
> On-call metadata, including type, id, and name.
>
> **Definition** - `oncall.details()`
>
> **Examples**
>
> To find all entities with a schedule-type on-call registration, you can use this expression in the Query builder:
>
> ```
> oncall.details().type == "schedule"
> ```
>
> If you're migrating on-call policies, you could use this rule to check for outdated policies. For example, assume that all outdated PagerDuty policies start with "Legacy" in their titles.
>
> ```
> oncall.details().id.matches("Legacy*") == false
> ```
>
> Entities with on-call policies that start with "Legacy" fail, while those with other policy names pass.

## Triggering an incident

A given entity can have a PagerDuty service, schedule, or escalation policy defined, as described in [Connecting via an entity descriptor](https://docs.cortex.io/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty.md#connecting-via-an-entity-descriptor). Only entities with a PagerDuty service defined include the option to trigger an incident directly from Cortex.

Your PagerDuty API key must include the `Write` permission to trigger incidents from an entity.

**To trigger an incident in PagerDuty**:

1. In Cortex, navigate to an entity.
2. From the entity's left sidebar, select **Incidents**.

   ![The 'Incidents' tab on the entity's left sidebar.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/pagerduty-incidents.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=1034a670d1a58a71e3f53d461cf289ab)
3. In the upper-right corner of the **Incidents** page, click **Trigger incident**. The **Trigger incident** side panel opens.
4. Do the following:
   1. Under **Title**, enter a name for the incident (required).
   2. Under **Description**, enter a description of the incident.
   3. From the **Urgency** dropdown, select a severity level.
5. Click **Trigger incident**.
6. Click **Click here** to view the incident in PagerDuty.
7. Click **Close** to collapse the **Trigger incident** side panel.

## Viewing PagerDuty integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.


## Related topics

- [Connecting entities to PagerDuty](https://docs.cortex.io/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty.md)
- [PagerDuty](https://docs.cortex.io/ingesting-data-into-cortex/integrations/pagerduty.md)
- [PagerDuty API](https://docs.cortex.io/api/rest/integrations/pagerduty.md)