❗️

End-of-Life

Rulesets and Event Rules webpages reached end-of-life on January 31, 2025 and are no longer visible in the PagerDuty web app. We highly recommend that you migrate to Event Orchestration as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting.

Access and modifications to event rules are still possible via the API.

Customize Event Fields (Optional)

Dynamic Field Enrichment & Extraction

Dynamic Field Enrichment & Extraction is a tool used to normalize event payloads using Event Rules. This capability allows you to copy important data from any combination of source event fields into any PagerDuty Common Event Format (CEF) field. Translate difficult machine terms and code into helpful context for responders so they can effectively respond to the problem. Dynamic Field Enrichment & Extraction can also be used to enhance PagerDuty AIOps capabilities by customizing alerts, influencing the Intelligent Alert Grouping and Intelligent Triage machine learning algorithms.

📘

Custom Event Fields vs. Custom Fields on Incidents

This feature is intended to customize event fields within Alerts, as opposed to creating custom fields in the incident UI. To create the latter, please read Custom Fields on Incidents.

📘

Availability

This feature is available with the PagerDuty AIOps add-on. Please contact our Sales Team if you would like to purchase this product.

Dynamic Field Enrichment & Extraction is composed of two functions:

• Create Custom Variables: Capture snippets from a source event using regex matching for later use.
• Replace Common Event Format Fields: Enrich and update and CEF field or even create new key values within the Custom Details object using custom variables. When events are sent to PagerDuty, they are transformed into Common Event Format. Previously, Event Rules could only replace Summary or add a Deduplication Key, and these abilities were limited to a direct mapping from one field as a full replacement. Now, this ability is extended to replace any CEF field or even create new key values within the Custom Details object.

Dynamic Field Enrichment & Extraction is available with both Global Event Rules and Service Event Rules. For Service Event Rules, custom variables must extract from CEF fields of the event payload, where for Global Event Rules, custom variables can extract from any field of the event payload.

Global and Service Event Rules are evaluated against the original event. Fields created from Global Event rules via Dynamic Field Enrichment & Extraction cannot be evaluated by Service Event Rules.

Configure Dynamic Field Enrichment & Extraction

When using the API to create service event rules or event rules in a ruleset, you can use the extractions object in your request payload to define the source, value, and regex.

Set a Deduplication Key with Event Rules

The dedup_key field is used to merge events into a single alert. Events with the same dedup_key can update the status of the alert they are automatically merged into.

Below is an example of a ruleset configured to set a deduplication key using the details.error_summary field:

{
  "ruleset": {
    "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b",
    "position": 0,
    "disabled": false,
    "catch_all": false,
    "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b",
    "conditions": {
      "operator": "and",
      "subconditions": [
        {
          "operator": "contains",
          "parameters": {
            "value": "mysql",
            "path": "details.host"
          }
        }
      ]
    },
    "time_frame": {
      "active_between": {
        "start_time": 1577880000000,
        "end_time": 1580558400000
      }
    },
    "actions": {
      "annotate": {
        "value": "This incident was created by a Global Event Rule"
      },
      "route": {
        "value": "PI2KBWI"
      },
      "priority": {
        "value": "PCMUB6F"
      },
      "severity": {
        "value": "warning"
      },
      "extractions": [
        {
          "target": "dedup_key",
          "source": "details.error_summary",
          "regex": "Host (.*) is experiencing errors"
        }
      ]
    }
  }
}

Add or Replace the Summary Field with Event Rules

The summary field is used to create the incident title. Titles should be descriptive and tell responders what is happening.

Below is an example of a rule using a custom variable to replace the default summary value with a custom error_title field value:

{
  "rule": {
    "actions": {
      "annotate": null,
      "automation_actions": [],
      "event_action": null,
      "extractions": [
        {
          "regex": null,
          "source": null,
          "target": "summary",
          "template": "{{newSummary}}"
        }
      ],
      "priority": null,
      "route": {
        "value": "P9XD19J"
      },
      "severity": null,
      "suppress": null,
      "suspend": null
    },
    "catch_all": false,
    "conditions": {
      "operator": "and",
      "subconditions": [
        {
          "operator": "contains",
          "parameters": {
            "path": "payload.source",
            "value": "webAPI"
          }
        }
      ]
    },
    "disabled": false,
    "id": "a1582b38-e753-486a-bc5c-bb7c6895e00c",
    "position": 0,
    "self": "https://api.pagerduty.com/rulesets/1d9089cd-fc3a-406e-9ddc-625bbeb43601/rules/a1582b38-e753-486a-bc5c-bb7c6895e00c",
    "time_frame": null,
    "variables": [
      {
        "name": "newSummary",
        "parameters": {
          "path": "payload.custom_details.error_title",
          "value": "(.*)"
        },
        "type": "regex"
      }
    ]
  }
}

Using Dynamic Field Enrichment & Extraction for Email Events

Dynamic Field Enrichment & Extraction capabilities are available only for email events sent to Global Event Rules. Users can extract from the email event using regex matching into multiple variables. Currently, only Summary and Dedup_Key Common Event Fields can be replaced for email events.

Service Event Rules do not apply to emails because they aren’t CEF and therefore, dynamic field enrichment & extraction capabilities are not available for email service integrations.

Enhancing Alert Grouping Capabilities

Dynamic Field Enrichment & Extraction can be powerfully leveraged for improving the accuracy for Intelligent Alert Grouping and Content Based Alert Grouping. This capability can add and replace key information from the raw event payload to create more contextualized alerts, allowing for more flexible and accurate alert grouping options.

Paused Incident Notifications

As a feature of Rulesets, paused incident notifications allows rules to be set to create alerts, but pause incident creation and notifications for a predefined amount of time. During the pause period, new alerts will be viewable in the Alerts table with a Suspended status. These suspended alerts have new actions, allowing users to Trigger an incident from the alert during the pause period, or Resolve the alert, preventing the incident and its notifications from being created altogether.

📘

Availability

• The Paused Incident Notifications functionality is part of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.
• Paused Incident Notifications is only available on incidents generated by our Events API, and does not work with those generated from our REST API.

To configure paused incident notifications, please refer to our API documentation for more information.

View and Take Action on Paused Alerts

To view alerts in a paused state, navigate to the Alerts table in the upper menu of the web app. Alerts with paused incident notifications will have a Suspended status:

To take action on a paused alert:

1. Click the incident title to view its details page.
2. On the right hand side, click Trigger to trigger an incident and send notifications, or Resolve if you would like to resolve the alert without triggering an incident/notifications. You will see a green dialog that confirms that the alert has been triggered or resolved.

The pause period and action taken will also appear in the Alert Log timeline, accessible by clicking an alert's title to view the detail page:

Suppress, but Create Triggering Thresholds with Event Rules

Receive PagerDuty notifications only when your customized alert conditions breach your specified limits. In this way, responders effectively reduce alert noise without missing critical issues.

📘

Availability

The Threshold Alerts functionality is part of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.

To configure triggering thresholds for suppressed incidents, please refer to our API documentation for more information.

Set Severity with Event Rules

For events that do not have a severity level (such as emails), users can define one, or a new severity level can be set. All current pricing plans include incident severity.

To set severity, please refer to our API documentation for more information.

Set Incident Urgency with Event Rules through Dynamic Notifications

Severity can be used for Dynamic Notifications, which are defined by the service settings. To use Dynamic Notifications, the events must be routed to a service that sets Dynamic Notifications based on severity levels.

With severity controlled via event rules and the service configured to use dynamic notification, you can control the incident urgency.

Set Priority with Event Rules

Incident priority allows the classification of incidents based on a level of prioritization. Incident priority must be enabled on your account before it can be set with event rules.

To set priority, please refer to our API documentation for more information.

Add a Note to an Incident with Event Rules

Notes can be used to help responders resolve incidents quicker by including information or links related to the system that the event comes from.

📘

Notes

• Adding notes via event rules is available with our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.
• The note is added when an incident is created. If a new alert is deduplicated into the incident, then the deduplicated alert will not add an additional note nor change the original.

To add a note with event rules, please refer to our API documentation for more information.

Set a Custom Trigger / Resolve Action with Event Rules

If you would like to automatically trigger an alert or resolve an alert based on your event rule conditions, under Enrichment & Transformations, please refer to our API documentation for more information on configuring this action. All pricing plans include incident custom trigger/resolve actions with event rules.

Automated Triggers

Automated Triggers allow response teams to easily define a dynamic webhook using event rules, sending a custom payload to a specified endpoint. This enables responders to automate actions like restarting a server, clearing logs, and reverting bad deploys. The payload can be set using a combination of several predefined variables, created using Dynamic Field Enrichment and Extraction. Automated Triggers can be created using both global event rules and service level event rules.

📘

Availability

Automated Triggers are a feature of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.

Configure Automated Triggers

To configure automated triggers, please refer to our API documentation for more information.

Use Automated Triggers

Once the rule is created, a custom push-button action will be available the next time the rule is applied. Users can find the Automated Triggers action in the More... dropdown on the incident details page, and activity related to the custom rule action will be visible in the incident timeline.

There is a limit of one Automated Trigger per rule. If Intelligent Alert Grouping is enabled on a Service, each additional alert grouped to the incident can add an additional unique action button, up to a limit of 5 buttons.

A modal will appear when the Automated Triggers action is clicked, and users can confirm the details of the webhook payload (fields were set in the rule configuration phase). For all webhooks, the PagerDuty incident ID will be included as a mandatory field. If the action is triggered, a response log will be shown in the incident timeline to let users know if the webhook was successfully received.

Configure Time Frame

While configuring a rule via the API, you can optionally define a specific time frame or schedule for when you would like this rule to be active using the time_frame object.

If you omit time_frame from your request, this rule will always run (24/7/365) when your conditions are met.

Scheduled Event Rules

You can gain a greater degree of control over your event rules by detailing a single specific time in the future in which they will be active. This can be useful for testing rules and for planned maintenance. Users can then specify what actions are to be performed within this specific time window. For instance, if you schedule a rule to be active during a single hour window, and the action set was to suppress alerts, alerts would be suppressed during that hour, and once it ended they would begin generating incidents again.

📘

Availability

Scheduled Rules functionality is available with our Business, Enterprise for Incident Management and Digital Operations (Legacy) plans, or as part of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.

Recurring Event Rules

If there are specific hours of the day or day(s) within a week when you would like an event to follow a particular rule, you can set its activity on an automatic, weekly recurring schedule. This feature is specific to each individual event rule and you can make additional changes, such as changing severity/priority, based on time of day.

📘

Availability

The Recurring Event Rules functionality is available with our Business, Enterprise for Incident Management and Digital Operations (Legacy) plans, or as part of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.

Send Test Events

🚧

Unsupported Integration Types

The following types of integrations cannot use ruleset integration keys:

• Integrations that connect via account authorization are not supported.
• Custom Event Transformer integrations are not supported.
• Integrations that use the REST API are not supported.

Send Events to a Global Ruleset

Each global ruleset will have a routing integration key, as well as an HTTP endpoint for API and email address that you can use for routing.

The HTTP endpoint used for rulesets is https://events.pagerduty.com/v2/enqueue. You can view a ruleset's routing key by making a request to the Get a Ruleset endpoint. A ruleset's email address will follow the formula routing_key@your_subdomain.pagerduty.com.

Use this information to send events based on your preferred integration method:

• Use the Integration Key to integrate with your preferred tool.
• Use the Integration Key to send an event through one of the Events APIs.
  • If using the V2 events API, use your routing Integration Key as your routing_key value in your event JSON.
  • If using the V1 events API, use your routing Integration Key as your service_key value in your event JSON.
• Use the Email address to send email events.

📘

Case Sensitivity

Integration keys are case-sensitive.

This will allow you to test how your event rules will modify them and take the actions configured in previous steps. Your event rule is now complete! If you would like to create more event rules, repeat steps 1-4 as needed.

Send Events to Service Event Rules

Add your preferred tool integration or a Custom Event Transformer integration on the service where you configured the above rule(s). Once you have added the integration to your service, you will be directed to the Integrations tab, where you can access its Integration Key:

Use this Integration Key to complete your integration and send test events to your service. This will allow you to test how your event rules will modify them and take the actions configured in previous steps. Your event rule is now complete! If you would like to create more event rules, repeat steps 1-4 as needed.