Included a documentation directory

[osm/MON.git] / doc / plugins / OpenStack / aodh_plugin_guide.rst

diff --git a/doc/plugins/OpenStack/aodh_plugin_guide.rst b/doc/plugins/OpenStack/aodh_plugin_guide.rst
new file mode 100644 (file)
index 0000000..b19eca3
--- /dev/null
+++ b/doc/plugins/OpenStack/aodh_plugin_guide.rst
@@ -0,0 +1,124 @@
+..
+       # 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