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.
Cortex runs the following background jobs for PagerDuty:
- On-call information on the Engineering homepage is refreshed every 60 minutes.
- Services used for automapping and active incidents are fetched approximately every 5 minutes, or however long the refresh takes.
- User data for identity mapping is synced daily at 10 a.m. UTC.
Connecting an entity to PagerDuty
Cortex entities are connected to PagerDuty in one of two ways: automatically through discovery, or explicitly by defining a PagerDuty service, schedule, or escalation policy in the entity’s descriptor YAML.Discovering entities automatically
By default, Cortex uses the Cortex tag (e.g.checkout-api) or the entity’s name as the “best guess” for PagerDuty services. For example, if the Cortex tag is checkout-api, the corresponding service in PagerDuty should also be checkout-api.
If your PagerDuty services don’t cleanly match the Cortex tag or name, define the connection in the entity descriptor instead.
Considerations for registering PagerDuty entities
Cortex recommends setting up PagerDuty at the service level by registering service entities with PagerDuty services, rather than configuring team entities with a PagerDuty schedule. If PagerDuty is set up on a service level, you can see current on-call information listed within a given service’s page. If PagerDuty is set up on the team level, you can only view on-call rotation information from a team page. Other benefits of setting up PagerDuty on a service level include:- Structuring PagerDuty 1-1 with services enables better alert routing and analytics, something organizations struggle with more when PagerDuty is set up on a team level.
- With a service-level setup, it’s easier to enforce a compliant on-call policy for all services in PagerDuty, especially when making use of Scorecards.
- The service-level setup is less reliant on team members tagging incidents with service information because services and incidents are already linked.
- You gain the ability to get data from your Cortex catalog into PagerDuty, such as tier and criticality. By tying the service entities in the catalog to those in PagerDuty, you can automate processes and streamline severity protocols.
Viewing on-call data only
If you only want to view on-call data for entities, and do not want incidents displayed in Cortex, you can register the escalation policy ID for an entity. See Defining an escalation policy below.Connecting via entity descriptor
To explicitly connect an entity to PagerDuty, add thex-cortex-oncall block to the entity’s YAML, specifying a PagerDuty service, schedule, or escalation policy.
The YAML examples on this page show only the
x-cortex-* block. When you add one to an entity descriptor, nest it inside the info section. Blocks at the root level of the file are ignored without an error. For a full example, see Defining entities with YAML.Defining a PagerDuty service
In PagerDuty, find the service ID value. The URL for the service contains the ID, e.g.PDEF456 in https://yourdomain.pagerduty.com/services/PDEF456.
You can only configure one service ID per entity.
Defining a schedule
In PagerDuty, find the schedule ID. The URL for the schedule contains the ID, e.g.PABC123 in https://yourdomain.pagerduty.com/schedules/PABC123.
You can only configure one schedule per entity.
Defining an escalation policy
In PagerDuty, find the escalation policy ID. The URL for the escalation policy contains the ID, e.g.P7LVMYP in https://yourdomain.pagerduty.com/escalation_policies/P7LVMYP. You can only configure one escalation policy per entity.
Linking a Cortex entity to a PagerDuty escalation policy surfaces only on-call information in Cortex, not incidents. This is useful for teams that want to show on-call schedules without incident visibility.
Identity mappings
Cortex maps email addresses in your PagerDuty instance to email addresses that belong to team members in Cortex. When identity mapping is set up, users can see their personal on-call status from the Engineering homepage.Enabling the On-call Assistant
The On-call Assistant only works for service-level PagerDuty registrations, since these notifications are related to affected services.