Added a guide for creating Aodh alarms with new plugin meter/metrics.

Change-Id: I4c976303bb4dd5d479656778ae6d0742b2d42bf9

doc/source/alarms_guide.rst

@@ -0,0 +1,117 @@
+..
+      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.
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+=========================================
+Enabling Alarms for plugin metrics/meters
+=========================================
+
+This guide provides a description of what Aodh features are available when
+either the collectd-gnocchi or the collectd-ceilometer plugin are enabled.
+It provides a list of the alarms that can be created and how to create them.
+
+collectd-gnocchi-plugin
+-----------------------
+
+There are three types of gnocchi based alarms that can be created using Aodh:
+
+- gnocchi_resources_threshold
+- gnocchi_aggregation_by_metrics_threshold
+- gnocchi_aggregation_by_resources_threshold
+
+ .. note::
+
+       Currently, the metrics created by the collectd-gnocchi-plugin don't
+       support the creation of gnocchi_resources_threshold alarms or
+       gnocchi_aggregation_by_resources_threshold alarms.
+
+To create a simple gnocchi_aggregation_by_metrics_threshold alarm:
+
+- Type the following;
+
+::
+
+  aodh alarm create
+
+- In the same command specify the name, type, metrics, threshold and
+  aggregation method of your desired alarm. This alarm can be defined for one
+  or a list of metrics.
+
+::
+
+  --name <ALARM_NAME>
+  -t gnocchi_aggregation_by_metrics_threshold
+  --threshold <THRESHOLD>
+  --metrics <LIST_OF_METRICS>
+  --aggregation-method <AGGREGATION_METHOD>
+
+
+collectd-ceilometer-plugin
+--------------------------
+
+When this plugin is enabled threshold alarms can be defined for the new meters
+that enabling this plugin generates.
+
+- Threshold alarms can be created for meters via the following command;
+
+::
+
+  aodh alarm create
+  --name <ALARM_NAME>
+  -t threshold
+  -m <METER_NAME>
+  --threshold <THRESHOLD>
+
+
+Event Alarms
+------------
+
+Event alarms can be created for either of these plugins. They can be triggered
+by any type of event that can occur to either meters generated by the
+ceilometer plugin or metrics from the gnocchi-plugin.
+
+- To create event alarms enter the following command;
+
+::
+
+  aodh alarm create
+  --name <ALARM_NAME>
+  -t event
+  --event-type <EVENT_TYPE>
+
+
+Composite Alarms
+----------------
+
+Like event alarms, composite alarms can be created for both the gnocchi and
+ceilometer plugins. A composite alarm is created by combining more than one
+type of alarm. Hence you can combine gnocchi and ceilometer based alarms.
+
+- Composite alarms are generated by the following command;
+
+::
+
+  aodh alarm create
+  --name <ALARM_NAME>
+  -t composite
+  --composite-rule <COMPOSITE_RULE>
+
+

doc/source/devstackGSG.rst

@@ -108,3 +108,8 @@ To enable aodh with collectd, add the following to your local.conf:
 
    enable_plugin collectd-ceilometer-plugin http://github.com/openstack/collectd-ceilometer-plugin
    COLLECTD_AODH_ENABLED=True
+
+In addition to this, alarms can be created manually via the Aodh command line
+based on the metrics generated by the gnocchi plugin and meters from the
+ceilometer plugin. For more information on this please read
+doc/source/alarms_guide.rst.