Oracle Cloud Infrastructure Documentation

Scenario B: Send Alarm Messages to a Slack Channel

This topic explains how to set up automatic notifications to a Slack channel when alarms are triggered.

This scenario involves creating a Slack channel and creating an alarm  that sends a message to that channel. 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 as well as your email.

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  you should 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.

Setting Up This Scenario

Once you create an incoming webhook to your Slack app, setup is easy in the Console. Alternatively, you can use the Oracle Cloud Infrastructure CLI or API, which lets you execute the individual operations yourself.

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

Using the Console

This section walks through creating an alarm using the Console and then updating the topic created with the alarm.

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.

Task 1: Create the alarm

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 email subscription later.

  1. Open the navigation menu. Under Solutions and Platform, go to Monitoring and 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
      • 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".)
Task 2: 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. Under Solutions and Platform, go to Application Integration and 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 a 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. To this topic, add subscriptions referencing your Slack endpoint (including the webhook token) and an optional email address.

    • 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 email 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 "EMAIL" --subscription-endpoint "john.smith@example.com"

  3. 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: cp.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 endpoint (including the webhook token) and an optional email address.

    Example CreateSubscription request: Slack
    POST /20181201/subscriptions
                            Host: cp.notification.us-phoenix-1.oraclecloud.com
                            <authorization and other headers>
                            {
                            "topicId": "<topic_OCID>",
                            "compartmentId": "<compartment_OCID>",
                            "protocol": "SLACK",
                            "endpoint": "<slack-endpoint>"
                            }
    Example CreateSubscription request: Email
    POST /20181201/subscriptions
                            Host: cp.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.