Oracle Cloud Infrastructure Documentation

Scenario B: Send Alarm Messages to Slack and SMS

This topic explains how to set up automatic notifications to a Slack channel and an SMS phone number when alarms are triggered.

This scenario involves setting up a Slack endpoint for a channel and creating an alarm  that sends a message to both that channel and an SMS phone number. When the alarm fires, the Notifications service sends the alarm message to the destination topic, which then fans out to the topic's subscriptions. In this scenario, the topic's subscriptions include the Slack channel and SMS phone number as well as your email address.

This image shows Notifications in the context of a scenario that sends alarm messages to Slack.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

If you're a member of the Administrators group, you already have the required access to execute this scenario. Otherwise, you need access to Monitoring and Notifications.

Task 1: Set up your Slack endpoint

Create an incoming webhook to your Slack app.

Example of an incoming webhook to a Slack app (equivalent to the Slack endpoint for your subscription): https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Once you set up your Slack endpoint, you can complete all other scenario steps in the Console. Alternatively, you can use the Oracle Cloud Infrastructure CLI or API, which lets you execute the individual operations yourself.

Task 2: Create the alarm, topic, and subscriptions

You can create the alarm, topic, and subscriptions in the Console, CLI, or API.

Using the Console

This section walks through creating the alarm, topic, and subscriptions using the Console.

Note

Another workflow for this scenario involves creating your topic and subscriptions first, then selecting this topic when you create your alarm.

For help with troubleshooting, see Troubleshooting Notifications.

Create the alarm, topic, and Slack subscription

This example walks through using the Console to create an alarm that sends a message to Slack when a high CPU usage is detected. During this process, you'll create a topic that references your Slack channel (Slack endpoint, including the webhook token). You can add the SMS and email subscriptions later.

  1. Open the navigation menu and click Observability & Management. Under Monitoring, click Alarm Definitions.

  2. Click Create alarm.

  3. On the Create Alarm page, under Define alarm, set up your threshold: 

    • Metric description: 
      • Compartment: (select the compartment  that contains your VM)
      • Metric Namespace: oci_computeagent
      • Metric Name: CpuUtilization
      • Interval: 1m
      • Statistic: Count

    • Trigger rule:

      • Operator: greater than
      • Value: 90
      • Trigger Delay Minutes: 1
  4. Add your Slack endpoint under Notifications, Destinations:
    • Destination Service: Notifications Service
    • Compartment: (select the compartment  where you want to create the topic and associated subscriptions)

    • Topic: Click Create a topic

      Note

      If you already created your topic and Slack subscripton, you can select that topic here instead of creating a new one.
      • Topic Name: Alarm Topic. Avoid entering confidential information.
      • Subscription Protocol: Slack
      • URL: Your Slack endpoint, including the webhook token.
  5. Click Save alarm.
  6. Confirm your new Slack subscription: Navigate to the confirmation URL that is sent to the Slack channel. (Look for the message containing the phrase "To confirm the subscription".)
Add an SMS subscription

This example walks through using the Console to add an SMS subscription to the topic you created when you set up the alarm.

  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.

  2. Click the name of the topic that you want to add the subscription to.

    Example: "Alarm Topic" (assuming you used the suggested topic name when creating the topic in the alarm).

  3. On the topic detail page, click Create Subscription.

  4. In the Create Subscription dialog box, set up your SMS subscription:

    • Protocol: Select SMS.
    • Country: Select the country for the phone number.
    • Phone Number: Enter the phone number, using E.164 format.

      Example SMS endpoints:

  5. Click Create.

    The SMS subscription has been created and a subscription confirmation message is sent to the specified phone number. The subscription remains in "Pending" status until it has been confirmed.

  6. To confirm your new SMS subscription, follow the instructions in the received confirmation message. (Look for the message containing the phrase "REPLY 'CONFIRM" followed by your topic name.)
Add an email subscription (optional)

This example walks through using the Console to add an optional email subscription to the topic you created when you set up the alarm.

  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.

  2. Click the name of the topic that you want to add the subscription to.

    Example: "Alarm Topic" (assuming you used the suggested topic name when creating the topic in the alarm).

  3. On the topic detail page, click Create Subscription.

  4. In the Create Subscription dialog box, set up your email subscription:

    • Protocol: Select Email.
    • Email: Type an email address.

  5. Click Create.

    The email subscription has been created and a subscription confirmation URL is sent to the specified email address. The subscription remains in "Pending" status until it has been confirmed.

  6. To confirm your new email subscription, open your email and navigate to the confirmation URL.

Using the CLI

This section walks through creating the topic, subscriptions, and alarm using the CLI.

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.
  1. Create the topic

    Open a command prompt and run the oci ons topic create command: 

    oci ons topic create --name "Alarm Topic" --compartment-id "<compartment-ocid>"
  2. Add the subscriptions

    To the topic you just created in the previous step, add subscriptions referencing your Slack endpoint (including the webhook token) and an optional email address and SMS phone number.

    • Create a Slack subscription: Open a command prompt and run the oci ons subscription create command:

      oci ons subscription create --compartment-id "<compartment-ocid>" --topic-id "<topic-ocid>" --protocol "SLACK" --subscription-endpoint "<slack-endpoint>"

    • Create an SMS subscription: Open a command prompt and run the oci ons subscription create command:

      oci ons subscription create --compartment-id "<compartment-ocid>" --topic-id "<topic-ocid>" --protocol "SMS" --subscription-endpoint "<sms-endpoint>"

    • Create an email subscription (optional): Open a command prompt and run the oci ons subscription create command:

      oci ons subscription create --compartment-id "<compartment-ocid>" --topic-id "<topic-ocid>" --protocol "EMAIL" --subscription-endpoint "john.smith@example.com"
  3. Create the alarm

    Create an alarm that defines the CPU threshold and references this topic as the destination: Open a command prompt and run the oci monitoring alarm create command: 

    oci monitoring alarm create --display-name "VM Memory Alarm" --compartment-id "<compartment-ocid>" --metric-compartment-id "<compartment-ocid>" --namespace "oci_computeagent" --query-text "CPUUtilization[1m].count() > 90" --severity "CRITICAL" --destinations "<topic-ocid>" --is-enabled true

For help with troubleshooting, see Troubleshooting Notifications.

Using the API

This section walks through creating the topic, subscriptions, and alarm using the API.

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following operations:

  1. CreateTopic: Create a topic.

    Example CreateTopic request
    POST /20181201/topics
Host: notification.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
  "name": "Alarm Topic",
  "compartmentId": "<compartment_OCID>"
}

  2. CreateSubscription: To this topic, add subscriptions referencing your Slack channel and optionally your email address and SMS phone number.

    Example CreateSubscription request: Slack
    POST /20181201/subscriptions
Host: notification.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
  "topicId": "<topic_OCID>",
  "compartmentId": "<compartment_OCID>",
  "protocol": "SLACK",
  "endpoint": "<slack-endpoint>"
}
    Example CreateSubscription request: SMS
    POST /20181201/subscriptions
Host: notification.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
  "topicId": "<topic_OCID>",
  "compartmentId": "<compartment_OCID>",
  "protocol": "SMS",
  "endpoint": "<sms-endpoint>"
}
    Example CreateSubscription request: Email
    POST /20181201/subscriptions
Host: notification.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
  "topicId": "<topic_OCID>",
  "compartmentId": "<compartment_OCID>",
  "protocol": "EMAIL",
  "endpoint": "john.smith@example.com"
}

  3. CreateAlarm: Create an alarm that defines the CPU threshold and references this topic.

    Example CreateAlarm request
    POST /20180401/alarms
Host: telemetry.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
  "displayName": "CPU Alarm",
  "compartmentId": "<compartment_OCID>",
  "metricCompartmentId": "<compartment_OCID>",
  "namespace": "oci_computeagent",
  "query": "CPUUtilization[1m].count() > 90",
  "severity": "CRITICAL",
  "destinations":
  [
    "<topic_OCID>"
  ],
  "isEnabled": true
}

For help with troubleshooting, see Troubleshooting Notifications.