Oracle Cloud Infrastructure Documentation

PagerDuty Integration Walkthrough

Learn how to integrate Oracle Cloud Infrastructure Notifications with PagerDuty so you can trigger PagerDuty incidents.

Create a PagerDuty Endpoint

To complete this procedure, you must have one of the following roles in PagerDuty: Manager, Admin, Global Admin, or Account owner base role.

  1. Go to PagerDuty.
  2. From the Configuration menu, select Services.
  3. On your Services page:
    1. If you are creating a service for your integration, select +Add New Service.
    2. If you are adding your integration to an existing service, select the name of the service you want to add the integration to. Then select the Integrations tab and select the +New Integration button.
  4. Type an Integration Name in the format monitoring-tool-service-name.

    If you are creating a service for your integration, in Incident Settings, specify the Escalation Policy, Notification Urgency, and Incident Behavior for your new service.

  5. Select your preferred endpoint type from the Integration Type menu based on the following options:

    • Oracle Cloud Infrastructure Monitoring: If you only want messages published by alarm (using the alarm message format). For this endpoint type, PagerDuty responds according to message format:

      • Messages that use the generic message formats are ignored. For example, if your event rule triggers the publication of a message to the topic containing this subscription, or if you directly publish a message to the topic using the Notifications service, then no PagerDuty incident is created.
      • Messages that use the alarm message format are processed. For example, if your alarm triggers publication of a message to the topic, which is in the alarm message format, then a PagerDuty incident is created.

    • Custom Event Transformer: If you want any messages to generate a PagerDuty incident, whether they come from event rules, alarms, connectors, console announcements, or direct publications. Messages sent to this endpoint follow the generic message format.

      For more information about Custom Event Transformer, see the PagerDuty documentation.

  6. Select the Add Service or Add Integration button to save your new integration.
    You are redirected to the Integrations page for your service.
  7. Copy the Integration Key and the Integration URL for your new Integration and keep it in a safe place for later use.

    Example of a PagerDuty Integration Key and Integration URL (at the time this document was published):

    PagerDuty Integration Key and Integration URL.
    You now have the integration key needed to create a PagerDuty subscription in Notifications.

Create a PagerDuty Subscription

To complete this procedure, you must have access to Notifications and permissions to create topics and subscriptions. See Securing Notifications (IAM Policies).

  1. On the Topics list page, select Create Topic. If you need help finding the list page, see Listing Topics.
  2. In the Create Subscription panel, for Protocol, select PagerDuty.

    The URL field is displayed with a space for you to add the integration key.

    Integration Key section of PagerDuty endpoint.

    • Protocol: Select PagerDuty.

    • URL: 

      Type (or copy and paste) the integration key portion of the URL for your PagerDuty subscription. This portion is the PagerDuty endpoint. (The other portions of the URL are hard-coded.)
  3. Select Create.

    The PagerDuty subscription has been created. It remains in "Pending" status until confirmation is received.

  4. Confirm the new PagerDuty subscription:
    1. Go to PagerDuty.
    2. Access the incident titled "Oracle Notification Service Subscription Confirmation."
    3. Select the Confirmation URL link.

    Example of confirmation incident (at the time this document was published):

    Example of confirmation incident in PagerDuty.
    Now that you have a confirmed subscription that references your PagerDuty endpoint, you can test the integration by directly publishing a message to its parent topic.

Test a PagerDuty Subscription (Direct Publish)

To complete this procedure, you must have access to Notifications and permissions to publish messages. See Securing Notifications (IAM Policies).

    1. On the Topics list page, find the topic that you want to work with. If you need help finding the list page or the topic, see Listing Topics.
    2. From the Actions menu (Actions Menu) for the topic, select Publish Message.
    3. In the Publish Message dialog box, provide values for the following fields: enter the items required by your integration type.

      • For Custom Event Transformer, enter a Message and Title.

        Example Message: "Non-optimal utilization detected. An application or process may be consuming more CPU than usual."

        Example Title: "Non-Optimal Alarm"

      • For Oracle Cloud Infrastructure Monitoring, enter a Message containing a JSON blob with key-value pairs for severity (string, required) and one or more of the following: title (string), body (string), and alarmMetaData (JSON blob or array).

        Example JSON blob:
        {
  "title": "my test alarm",
  "body": "my test body",
  "severity": "warning",
  "alarmMetaData": {
    "key1": "value1",
    "key2": "value2"
  }
}

        The severity value is flexible for testing. For production, use a PagerDuty-supported value, such as critical, error, warning, or info.

    4. Select Publish.

      A PagerDuty incident is triggered containing the content of your message.

      Example of triggered PagerDuty incident (at the time this document was published):

      Example of triggered PagerDuty incident.

      Example of the content of a triggered PagerDuty incident (at the time this document was published):

      Example of content in a triggered PagerDuty incident.

      You have confirmed that directly publishing a message triggers a PagerDuty incident. Next, use your new subscription to trigger PagerDuty incidents from alarms, events, and connectors.

      Note

      To check the endpoint URL or other details of the PagerDuty subscription, see Getting a Subscription's Details. For troubleshooting information related to published messages, see Message Not Received.

  • Use the oci ons message publish command and required parameters to publish a message to a topic:

    oci ons message publish --body <message_text> --topic-id <topic_OCID>

    For a complete list of parameters and values for CLI commands, see the Command Line Reference for Notifications.

  • Run the PublishMessage operation to publish a message to a topic.

    Example request for a PagerDuty endpoint of the Custom Event Transformer type:

    POST /20181201/topics/<topic_OCID>/messages
Host: <topic API endpoint>
<authorization and other headers>
{
  "title": "Non-Optimal Alarm",
  "body": "Non-optimal utilization detected. An application or process may be consuming more CPU than usual."
}

Trigger a PagerDuty Incident

Trigger an incident in PagerDuty from an alarm, event, connector, or announcement subscription using a subscription in Notifications.

When creating an alarm, event rule, connector, or announcement subscription, select the Notifications topic that contains the PagerDuty subscription. For instructions on creating these resources, see the following documentation.

Note

To check the endpoint URL or other details of the PagerDuty subscription, see Getting a Subscription's Details.