Note:

Integrate OCI alerts with Syniverse SMS API

Introduction

In this tutorial, you’ll create an alert based on CPU utilization and configure Syniverse to send an SMS alert when it reaches the defined threshold.

The solution that we provide uses the Oracle Notifications Service (ONS) to deliver notifications of events and alarms to a Function that can call Syniverse SMS API, to send the SMS message. We build a production-ready solution where everything is parameterized and we also included Object store, where we stored the phone numbers to send the SMS and Oracle Vaults to stored the Syniverse API credentials.

We create ONS with one topic to receive the notification alert and one subscription to that topic to call Oracle function. We configure the monitoring alarm. For example, whenever the CPU Utilization exceeds 70%, an Oracle Function triggers ONS to call Syniverse endpoint to send the SMS.

The following diagram shows how this works.

Create a Syniverse Account and API key

  1. Go to the Syniverse Developer Community and create an account.

  2. Sign in to your Syniverse account, go to the Applications menu, and click Create New.

  3. Enter the following:

    • Application Name: oci
    • Description: Real-time SMS with OCI Alert or OCI logs
    • Account: Choose your initial account

  4. After creating the application, click the application name and expand Auth Keys to see the API details. We use this info on the Oracle Function and Vaults.

For more info, check here.

Create an OCI Compartment

  1. Sign in to the OCI Console as an Administrator and from the menu in the upper-left corner, select Identity, and then select Compartments.

  2. Click Create Compartment and use the following example to create the compartment:

    • Name: syniverse_compartment
    • Parent Compartment: Select a compartment (if you want to make it a child of an existing compartment, select the relevant parent compartment, otherwise accept the default root container)

Create an Oracle Vault

  1. From the menu in the upper-left corner, select Security, and then select Vault.

  2. Select syniverse_compartment that you created.

  3. Click Create Vault and create a vault with syniverse_api_credentials name.

  4. Choose your vault, click Create Key and create a key with syniverse_token name.

  5. Click on the Secrets link under Resources in the left navigation pane

  6. Click Create Secret and use the following example:

    • Name: secret_token
    • Encryption Key: Select the syniverse_token that you created earlier
    • Secret Contents: here you should add the Access token from Syniverse

  7. Click on the secret my-secret, copy the secret OCID and replace the value in func.yaml file

Create a Dynamic group for Oracle Vault.

  1. From the menu in the upper-left corner, select Identity, and then select Dynamic Groups.

  2. Click the Create Dynamic Group and use the following example:

    • Name: syniverse-secret-group
    • Rule: any {instance.compartment.id = ‘’}

Create a Bucket and Upload a File to Object Storage

  1. Create a Bucket.

    1. From the menu in the upper-left corner, select Core Infrastructure, and then select Object Storage.

    2. Select the compartment syniverse_compartment that you created.

    3. Click Create Bucket and create a Bucket with syniverse_phone_target_list name

  2. Create and upload a file with the phone number. The Function has an object store dependency because it reads the file with recipient phones to send the SMS.

    1. Create a local file called numbers.txt and add the phone number that you want to use for your case. The file should be comma delimited with no spaces.

    2. From the Object Storage details screen click Upload Objects and select the numbers.txt file to upload For example, the numbers.txt file may contain something like:

      +3530871231234, +35308712312345

      Optionally, you can add a Policy to restrict the access to this bucket or file to a few people.

  3. Create a dynamic group for Oracle Function read Object Storage.

    1. From the menu in the upper-left corner, select Identity, and then select Dynamic Groups.

    2. Click the Create Dynamic Group and use the following example:

      • Name: fn-obj-store-group
      • Rule: ALL {resource.type = ‘fnfunc’, resource.compartment.id = ‘'}

  4. Create a Policy for this dynamic group.

    1. From the menu in the upper-left corner, select Identity, and then select Policies.

    2. Click the Create Policy and use the following example:

      • Name: fn-obj-store-list-policy

      • Statements: on Policy Builder click in Cutmomize(advanced)

        allow dynamic-group fn-obj-store-list to manage all-resources in compartment my-compartment

Create a Virtual Cloud Network (VCN)

  1. From the menu in the upper-left corner, select Core Infrastructure, select Networking, and then select Virtual Cloud Networks.

  2. Select the compartment syniverse_compartment that you created.

  3. Click Start VCN Wizard and choose VCN with internet connectivity and click Start VCN Wizard.

  4. Add a VCN name and maintain all default values.

  5. Click Next and confirm to create the VCN.

Create an Oracle Function

  1. From the menu in the upper-left corner, select Developer Service, and then select Functions.

  2. Select the compartment syniverse_compartment that you created.

  3. Click Create Application and create an application with syniverse_notification name. Pick the compartment, VCN, and subnet that you created.

  4. Launch Cloud Shell.

  5. Use the context for your region:

    fn list contextfn list context
fn use context us-phoenix-1

  6. Update the context with the function’s compartment ID:

    fn update context oracle.compartment-id <**compartment-id**>

  7. Update the context with the location of the registry you want to use:

    fn update context registry phx.ocir.io/<tenancy_name>/[YOUR-OCIR-REPO]

    Replace phx with the three-digit region code.

  8. Click Generate an Auth Token.

    Sign in to the Registry using the Auth Token as your password: 

    docker login phx.ocir.io <-- Replace phx with the three-digit region code

    You are prompted for the following information:

    • Username: tenancyname/username
    • Password: Create a password

    Note: If you use Oracle Identity Cloud Service, your username is tenancyname/oracleidentitycloudservice/username.

  9. Generate a ‘hello-world’ boilerplate function:

    fn init --runtime python syniverse

    This function will create a folder “syniverse” with a simple fn python example.

    Replace the content of the files with the code below.

    1. Import the necessary Python modules, as shown in the following snippet:

      import io
import os
import oci
import json
import requests
import logging
import datetime
import base64
from fdk import response

    2. Define a function to parse the alart data and invoke the Syniverse API to send the SMS.

       if "body" in log:
     body = log.get("body")
 else:
     body = ""

 if "timestampEpochMillis" in log:
     time_in_millis = log.get("timestampEpochMillis") / 1000.0
     dt = datetime.datetime.fromtimestamp(time_in_millis).strftime('%Y-%m-%d %H:%M')
     body = body + "\ntime " + dt
 else:
     body = body + ""

    3. Invoke the Syniverse API, with the required payload.

       secret_token = os.environ['SYNIVERSE_TOKEN']
 response_token = read_secret_value(secret_client, secret_token)
 response_host = os.environ['SYNIVERSE_HOST']
 response_channel = os.environ['SYNIVERSE_CHANNEL']

 syniversehost = response_host
 syniversetoken = "Bearer " + response_token
 syniversechannel = "channel:" + response_channel

 payload = {}
 payload.update({"from":syniversechannel})
 payload.update({"to":phone})
 payload.update({"body":body})

      The config part contains the Object Store configurations, namespace, bucket name and file name along with the Syniverse configurations, Syniverse endpoint URL, and the token for authentication that you stored in the vault in Step 3.

      func.yaml

          schema_version: 20180708
    name: syniverse
    version: 0.0.335
    runtime: python
    entrypoint: /python/bin/fdk /function/func.py handler
    memory: 1024
    timeout: 120
    config:
SYNIVERSE_TOKEN: <i><paste OCID secret_token here></i>
SYNIVERSE_HOST: https://api.syniverse.com/scg-external-api/api/v1/messaging/message_requests
SYNIVERSE_CHANNEL: <Syniverse API channel>
SYNIVERSE_NAMESPACE: <OCI tenancy name>
SYNIVERSE_BUCKET_NAME: synivese_phone
SYNIVERSE_OBJECT_NAME: numbers.txt

      requirements.txt

      fdk
requests
oci

      notification sample json

      {"dedupeKey":"8303d9fb-e3b8-4d49-a888-64bef88f3dbd","title":"syniverse","body":"High CPU usage alert in \\"syniverse\\" instance","type":"OK_TO_FIRING","severity":"CRITICAL","timestampEpochMillis":1605622680000,"alarmMetaData":[{"id":"<i><paste OCID.alarm.oc1.phx.xxxxxxxxxxxxxxxxxxx></i>","status":"FIRING","severity":"CRITICAL","query":"CpuUtilization[1m]{resourceDisplayName = \\"instance-syniverse\\"}.max() > 70","totalMetricsFiring":1,"dimensions":[{"instancePoolId":"Default","resourceDisplayName":"instance-syniverse","faultDomain":"FAULT-DOMAIN-2","resourceId":"*<paste OCID here>*","availabilityDomain":"YVsm:PHX-AD-1","imageId":"<i><paste ocid1.image.oc1.phx.yyyyyyyyyyyyyyy></i>","region":"us-phoenix-1","shape":"VM.Standard.E3.Flex"}]}],"version":1.0}

      More details about Syniverse API can be found here.

  10. Create the app:

    fn create app syniverse --annotation oracle.com/oci/subnetIds= '["ocid1.subnet.oc1.phx.aaaaxxxxxxxxxxx"]'

    Change the subnetIds for your subnet OCID.

  11. Deploy your function:

    fn -v deploy --app syniverse

  12. Create a Policy for Oracle function.

    1. From the menu in the upper-left corner, select Identity, and then select Policies.

    2. Click the Create Policy and use the following example:

      • Name: oracle_funcgion_policy
      • Statements: on Policy Builder click in Cutmomize(advanced)
      allow service FAAS to use virtual-network-family in tenancy
allow service FAAS to read repos in tenancy

Create a Compute Instance

  1. From the menu in the upper-left corner, select Compute, and then select Instances.

  2. Click Create Instance and use the following example:

    • Name: instance-syniverse
    • Image: Leave default Oracle Linux 7.8 or select Oracle Linux 6.10
    • Change Shape: Select your shape
    • Configuring networking: Select the VCN, subnet compartment, and subnet that you created
    • Add SSH keys: Add your ssh rsa public key

Create a Topic and a Subscription for Oracle Notification Service

  1. From the menu in the upper-left corner, select Application Integration, and then select Notifications.

  2. Click Create Topic and create a topic with Syniverse_SNS_Notification name.

  3. Choose your topic, click Create Subscription and use the following example:

    • Protocol: function
    • Function Compartment: Select the compartment syniverse_compartment that you created
    • Function Application: syniverse_notification
    • Function: syniverse

Create an Alarm Definition

  1. From the menu in the upper-left corner, select Monitoring, and then select Alarm definitions.

  2. Click Create Alarm and use the following example:

    • Alarm Name: 70% CPU Utilization
    • Alarm severity: Critical
    • Alarm body: OCI Alarm: syniverse. CpuUtilization: 70

  3. On Metric description select the compartment syniverse_compartment, select Metric namespace as oci_computeagent, Metric name as CpuUtilization, Interval as 1m, and Statistic as Max

  4. On Trigger rule select Value greater than 70

  5. On Notification select Destination service as notification service, select the compartment syniverse_compartment, and select Topic as Syniverse_SMS_Notification

Install Stress Tools to do a Stress Test in your Compute Instance.

  1. SSH to your compute instance:

    ssh -i ~/path/for/ssh-key.key opc@your_machine_ip

  2. Install stress:

    sudo yum install stress

  3. Run the command to start the stress: This start the end-to-end demo flow.

    stress --cpu 20 --io 4 --vm 4 --vm-bytes 1024M --timeout 60s

Troubleshoot

This section shows how you can use a simple email alert to monitor the status of your solution.

Function

For more details on Functions, refer to the technical documentation.

Create a Topic and a Subscription for the Notification Service

  1. From the menu in the upper-left corner, select Application Integration, and then select Notifications

  2. Click Create Topic and create a topic with my_function_status name

  3. Choose your topic, click Create Subscription and use the following example:

    • Protocol: Email and add create a subscription with your email

  4. The subscription will be created in “Pending” status. You will receive a confirmation email and will need to click on the link in the email to confirm your email address.

Check Metrics and Create an Alarm Definition from Metrics

  1. From the menu in the upper-left corner, select Developer Services, and then select Functions

  2. Choose the application and the function that you want to monitor

  3. From the Metrics page, go to the “Functions Errors” chart, click on Options and Create an Alarm on this Query

  4. add a name and under Notification select Destination service as notification service, select the compartment your_compartment, and select Topic as my_function_status

Notification

This section shows how you can use a simple email alert to monitor the status of our Oracle Notification Service (ONS).

For more details refer to the technical documentation.

Create a topic and a subscription for the Notification Service

  1. From the menu in the upper-left corner, select Application Integration, and then select Notifications

  2. Click Create Topic and create a topic with my_ons_status name

  3. Choose your topic, click Create Subscription and use the following example:

    • Protocol: Email and add create a subscription with your email

  4. The subscription will be created in “Pending” status. You will receive a confirmation email and will need to click on the link in the email to confirm your email address.

Check Metrics and Create an Alarm Definition from Metrics

  1. From the menu in the upper-left corner, select Application Integration, and then select Notification

  2. Choose the notification that you want to monitor and click on metrics link under resources in the left navigation pane

  3. From the chart that you want to add the alarm e.g. “Failed Messages Count”, click on Options and Create an Alarm on this Query

  4. add a name and on Notification select Destination service as notification service, select the compartment your_compartment, and select Topic as my_ons_status

Conclusion

This tutorial shows how Oracle Cloud Infrastructure and Syniverse customers can configure a highly scalable solution with low-overhead for creating and sending SMS from Oracle Cloud Infrastructure alerts using Oracle Functions.

Acknowledgements

Author - Igor Aragao de Souza

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.