Change Events

Change events represent service changes such as deploys, build completion, configuration updates, etc., providing contextual information that is critical during incident triage or hypercare. They can be sent via specific integrations or API, and they do not create alerts, incidents or notifications. See the View Change Events section below for a list of places where change events are surfaced in PagerDuty.

Configure an Integration to Send Change Events

Change events can be sent via our change events integrations, which you can find in our integrations library, filtering the Category by Change:

You may follow the instructions in these integration guides to configure, or you can add them via the Recent Changes page.

Configure Integration via the Recent Changes Page

  1. Navigate to Incidents Recent Changes and click + New Change Integration to the right.
  2. Choose one of two options:
  • PagerDuty Integrations: If you would like to select a prebuilt integration, select your preferred vendor.
  • PagerDuty Events API: Select this option if you would like to create custom change events with the PagerDuty Events API.
  1. Select a service that you would like to add the integration to and click Next.
  2. On the next modal screen, copy your Integration Key and click View Documentation to see how to use the integration key to configure the rest of the integration.

Send Change Events via Events API

You may also send change events to integrations via the Events API v2.

View the Events API v2 Overview for guidance on when to send a change event instead of an alert event. You can send both event types using a single Events API v2 integration key.

Send Change Events via Custom Change Event Transformer

A Custom Change Event Transformer is also available that allows you to reliably convert a payload sent by integrations to a payload understood by PagerDuty as a change event.

View Change Events in the Web App

Change Correlation

Change Correlation provides responders with three recent change events that are most relevant to an incident. Each change event will have context as to why it was correlated based on three key factors: time, related service, or intelligence (machine learning). With valuable context available at a glance, responders can triage incidents quickly and reduce time-to-resolution.

📘

Note

  • Time Based Change Correlation is available to all customers.
  • Related Service Change Correlation and Intelligent Change Correlation are available to customers with the Event Intelligence add-on or on our Digital Operations plan.

View Change Correlations

  1. Navigate to an incident and click its Title to view the details page.
  2. You will see change correlations under Recent Changes. This section will list three recent change correlations within the last 24 hours, as well as a correlation reason.

Time Based Change Correlation

Time based change correlations will appear based on change events from the last 24 hours that have occurred on the same service as the incident. You can identify a time based correlation by viewing the context under the change event title that displays:

This incident occurred X minutes/hours after this change

Related Service Change Correlation

Related service change correlations will appear for change events that have occurred on technical and business services related to the service for that incident. You can identify a related service correlation by viewing the context under the change event title that displays:

This change occurred on a service related to [THIS INCIDENT’S SERVICE NAME]

Intelligent Change Correlation

Intelligent change correlations (machine learning) are determined by three main factors:

  • How close in time the previous incidents and change events occurred.
  • How related are the change event and incident metadata.
  • The frequency that a particular change event and incident occurred.

You can identify an intelligent change correlation by viewing the context under the change event title that displays:

Similar incidents have previously occurred with changes like this

Change Correlation via API

To access Change Correlation via API, please visit our API documentation.

View Change Events on a Service

Navigate to Services Service Directory and click the title of the integrated service. Under Recent Activity you will see change events labeled as RECENT CHANGE in grey in the timeline:

View and Filter All Change Events Across Services

To view and filter all change events across all services, navigate to Incidents Recent Changes. You may filter by Team, Service, integration Type and Last Changed time period.

View Change Event Details

To view a change event's details, click the change event's title and you will see the Service, Type, Timestamp, Summary, Source and Links to view the pull request, the integrated repository and the user's profile.

View Change Events in the Mobile App

Change Events will be available in two areas in the mobile app:

Incident Detail

To view change events in incident details, tap your desired incident and scroll to the Change Events section. Viewing change events within the incident details will display a maximum of two recent change events. Users will be able to view the details of the change event by selecting the to the right of the change event title.

The change event detail area will include Change Correlations. For more information on Change Correlations, see our article here.

Service Detail

To view change events within the service details, navigate to Service Directory and select your desired service. Viewing change events within the service details will display a maximum of two recent change events. Users will be able to view the details of the change event by selecting the to the right of the change event title.

FAQ

Is it possible to modify change events using event rules?

Not at this time, but we are interested to learn about what you would like to accomplish, please contact our Support team with your use cases and feedback.

Can change events be sent to a global integration key?

Not at this time. Change events must be sent to a service-specific integration key.

Is it possible to send change events to PagerDuty from applications that are not listed as a pre-built change event integration?

Yes, you can send change events to integrations via the Events API v2. A Custom Change Event Transformer is also available that allows you to reliably convert a payload sent by integrations to a payload understood by PagerDuty as a change event.

What is the time constraint for all change events on an incident?

Change events on an incident are constrained to 24 hours.

What types of services are represented in related service correlations?

Related service correlations can appear for technical and business services.

How do I configure Change Correlations?

As a prerequisite, in order to view Change Correlations you must have a change event integration configured. Once you have configured your change event integration(s), Change Correlation will work out-of-the box, with no additional setup required.

Why don’t I see change correlations on my incident?

Change correlations will only surface for change events that have occurred in the last 24 hours. Please ensure that your change event integrations are set up on all relevant services where you would expect your responders to see change events.

How do I improve the results of my change correlations?

For related service change correlations, ensure that you have your business and technical dependencies configured properly.

For intelligent correlation, the more change event data you send across your services, the more data the machine learning model will have to analyze and draw correlations between past change events and incidents.

Updated 21 days ago


Change Events


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.