..
       # Copyright 2017 Intel Research and Development Ireland Limited
       # *************************************************************
       # This file is part of OSM Monitoring module
       # All Rights Reserved to Intel Corporation
       #
       # Licensed under the Apache License, Version 2.0 (the "License"); you
       # may not use this file except in compliance with the License. You may
       # obtain a copy of the License at
       #
       #         http://www.apache.org/licenses/LICENSE-2.0
       #
       # Unless required by applicable law or agreed to in writing, software
       # distributed under the License is distributed on an "AS IS" BASIS,
       # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
       # implied. See the License for the specific language governing
       # permissions and limitations under the License.
       #
       # For those usages not covered by the Apache License, Version 2.0 please
       # contact: helena.mcgough@intel.com or adrian.hoban@intel.com

Aodh Plugin Guide for OSM MON
*****************************
The Aodh plugin for the MON module allows an OSM user to utilise the OpenStack
alarming functionality.

This plugin allows you to create, list, delete and update alarms. These alarms
are based on metrics generated by the OpenStack Gnocchi plugin.

Supported Alarms
----------------
Currently the plugin only supports the following alarms for their corresponding
metrics:

    +-----------------------------+---------------------------------+
    |      Gnocchi Metric         |            Aodh Alarm           |
    +-----------------------------+---------------------------------+
    | AVERAGE_MEMORY_UTILIZATION  | AVERAGE_MEMORY_UTILIZATION      |
    |                             |                                 |
    | DISK_READ_OPS               | DISK_READ_OPS                   |
    |                             |                                 |
    | DISK_WRITE_OPS              | DISK_WRITE_OPS                  |
    |                             |                                 |
    | DISK_READ_BYTES             | DISK_READ_BYTES                 |
    |                             |                                 |
    | DISK_WRITE_BYTES            | DISK_WRITE_BYTES                |
    |                             |                                 |
    | PACKETS_DROPPED             | NET_PACKETS_DROPPED             |
    |                             |                                 |
    | PACKETS_RECEIVED            | PACKETS_IN_ABOVE_THRESHOLD      |
    |                             |                                 |
    | PACKETS_SENT                | PACKETS_OUT_ABOVE_THRESHOLD     |
    |                             |                                 |
    | CPU_UTILIZATION             | CPU_UTILIZATION_ABOVE_THRESHOLD |
    +-----------------------------+---------------------------------+

Creating an Alarm
-----------------
To create an alarm for one of the supported metrics a no. of configuration
parameters must be set:

* alarm_name: Defines the name of the alarm and must correspond to the desired
  metric.
* metric_name: Defines the name of the metric for which the alarm is to be
  created.
* resource_uuid: Defines the resource that the chosen metric will monitor.
* severity: defines the significance of the alarm if it is triggered. Options
  for this parameter include:

    - WARNING
    - MINOR
    - MAJOR
    - CRITICAL
    - INDETERMINATE

* operation: Defines how the metric data is to be evaluated when determining if
  the alarm has been triggered. Valid inputs for this parameter include:

    - GE (greater than or equal to)
    - LE (less that or equal to)
    - GT (greater than)
    - LT (less than)
    - EQ (equal to)

* threshold_value: Defines a threshold that the metric values will be compared
  against to determine if the alarm should be triggered.
* statistic: Defines the way in which the metric data should be evaluated.
  Valid options for this parameter include:

    - AVERAGE
    - MINIMUM
    - MAXIMUM
    - COUNT
    - SUM

  .. note::

      - To create a valid alarm the metric that you request must exist as a
        Gnocchi metric and it must exist for the resource requested.
      - Multiple alarms can be created for the same metric as you can define
        different thresholds, operations, etc. for each alarm.

Deleting an Alarm
-----------------
To delete an alarm just before a delete request with the alarm_id of the alarm
you wish to delete.

Listing Alarms
--------------
A full list of alarms will be generated if a list request is performed and no
configuration parameters are set.

To generate a more specified list you can define one or both of the following
configuration parameters:

* alarm_name
* severity

  .. note::

    For now resource_uuid must be defined when generating a list of alarms.
    This will be removed in a future release.

Updating an alarm
-----------------
Certain parameters of an alarm can be updated after the alarm has been created.
These include:

* threshold_value
* operation
* statistic
* severity