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, click +Add New Service.
    2. If you are adding your integration to an existing service, click the name of the service you want to add the integration to. Then select the Integrations tab and click 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. Click 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 IAM Policies (Securing Notifications).

  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. Under List Scope, select a compartment that you have permission to work in.
    The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
  3. Click the name of the topic that you want to add the subscription to.
  4. On the topic detail page, click Create Subscription.
    The Create Subscription panel is displayed.
  5. 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.)

  7. Click Create.

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

  8. Confirm the new PagerDuty subscription:
    1. Go to PagerDuty.
    2. Access the incident titled "Oracle Notification Service Subscription Confirmation."
    3. Click 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 IAM Policies (Securing Notifications).

    1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
    2. Under List Scope, select a compartment that you have permission to work in.
      The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
    3. On the Topics page, for the topic you want, click the Actions menu (Actions Menu), and then click Publish Message.
      The Publish Message dialog box is displayed.
    4. In the Publish Message dialog box, 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.

    5. Click 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.