Scenario: Alarm on Log Data

This topic explains how to set up alarms for log data.

Caution

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

This scenario involves creating a service connector and an alarm. The service connector (Service Connector Hub)  processes and moves log data from Logging to Monitoring while the alarm  fires when triggered by received log data.

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.

The workflow for creating the service connector includes a default policy when needed to provide permission for writing to the target service.

Setting Up This Scenario

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.

Using the Console

This section walks through creating a service connector and 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 Service Connectors and Troubleshooting Notifications.

Task 1: Create the service connector

This example walks through using the Console to create a service connector that filters VCN flow log data from Logging for rejected traffic and then moves this log data to a new metric in Monitoring.

  1. Open the navigation menu. Under Data and AI, click Service Connector Hub.
  2. Choose the Compartment where you want to create the service connector.
  3. Click Create Service Connector.
  4. On the Create Service Connector page, filter VCN flow log data to a new metric:

    • Type a Connector Name such as "VCN Flow Log Errors."
    • Select the Resource Compartment where you want to store the new service connector.
    • Under Configure Service Connector, select your source and target services to move log data to a metric:
      • Select Source: Logging
      • Select Target: Monitoring
    • Under Configure source connection, select your VCN flow log:
      • Compartment: The compartment containing the VCN flow log data.
      • Log Group: The log group containing the VCN flow log data.
      • Logs: The log object name for your VCN flow logs.
    • Under Configure task, filter the log data to rejected traffic:

      • Property: data.action
      • Operator: =
      • Value: REJECT

      If you are interested in rejected traffic for a particular port or address, add another filter. For example, select the property data.destinationPort or data.destinationAddress.

    • Under Configure target connection, enter the metric namespace and metric name that you want to use for the filtered log data:
      • Select the Service Compartment where you want to store the metric data points corresponding to the VCN flow log data for rejected traffic.
      • Enter a new Namespace: vcnlogs.
        Note

        When typing a new metric namespace, press ENTER to submit it.
      • Enter a new Metric Name: rejectedtraffic
  5. If prompted to create a policy (required for access to create or update a service connector), click Create.
  6. Click Create.
Task 2: Create the alarm

This example walks through using the Console to create an alarm that sends a message when Monitoring receives metric data points corresponding to VCN flow log data for rejected traffic. During this process, you'll create a topic and an email subscription.

  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  specified in the previous task, where you are storing the metric data points corresponding to the VCN flow log data)
      • Metric Namespace: (enter the metric namespace that you specified in the service connector)
      • Metric Name: (enter the metric name that you specified in the service connector)
      • Interval1m
      • Statistic: Count 
    • Trigger rule:

      • Operatorgreater than
      • Value: 0
      • Trigger Delay Minutes: 1
  4. Under Notifications, Destinations, set up an email notification:
    • Destination ServiceNotifications 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 email subscription, you can select that topic here instead of creating a new one.
      • Topic Name: Rejected Traffic Topic
      • Subscription Protocol: Email
      • Email Addresses: (type your email address here)
  5. Click Save alarm.

Using the CLI

This section walks through creating the service connector, 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 service connector: Open a command prompt and run the oci sch service-connector create command:

    oci sch service-connector create --display-name
    "<display_name>" --compartment-id <compartment_OCID> --source [<source_in_JSON>] --tasks [<tasks_in_JSON>] --target [<targets_in_JSON>]
  2. 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>"
  3. To this topic, add a subscription referencing your email address. 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"
  4. Create an alarm that defines the error 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 "My Alarm" --compartment-id "<compartment-ocid>" --metric-compartment-id "<compartment-ocid>" --namespace "oci_computeagent" --query-text "<yourmetric>[1m].count() > 0" --severity "INFO" --destinations "<topic-ocid>" --is-enabled true

For help with troubleshooting, see Troubleshooting Service Connectors and Troubleshooting Notifications.

Using the API

This section walks through creating the service connector, topic, subscription, 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. CreateServiceConnector: Create a service connector.

    Example CreateServiceConnector request
    POST /20200909/serviceConnectors
    Host: service-connector-hub.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "compartmentId": "<compartment_OCID>",
      "description": "My service connector description",
      "displayName": "My Service Connector",
      "source": {
        "kind": "logging",
        "logSources": [
          {
            "compartmentId": "<compartment_OCID>",
            "logGroupId": "<log_group_OCID>",
            "logId": "<log_OCID>"
          }
        ]
      },
      "target": {
        "compartmentId": "<compartment_OCID>",
        "kind": "metrics",
        "metric": "<yourmetric>",
        "metricNamespace": "<yournamespace>"
      },
      "tasks": [
        {
          "condition": "data.action='REJECT'",
          "kind": "logRule"
        }
      ]
      }
    }
  2. 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>"
    }
  3. CreateSubscription: To this topic, add a subscription referencing your email address.

    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"
    }
  4. CreateAlarm: Create an alarm that defines the memory threshold and references this topic.

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

For help with troubleshooting, see Troubleshooting Service Connectors and Troubleshooting Notifications.