Add documentation about event alarm

The usage and configuration of event alarm functionality is missing.

Change-Id: I9938069f6cb8e27fb9e1ee7663f722dacb0368f6
Signed-off-by: liusheng <liusheng@huawei.com>

doc/source/event-alarm.rst

@@ -0,0 +1,86 @@
+..
+      Copyright 2014 Huawei Technologies Co., Ltd.
+
+      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.
+
+===========
+Event alarm
+===========
+
+Aodh allows users to define alarms which can be evaluated based on events
+passed from other OpenStack services. The events can be emitted when the
+resources from other OpenStack services have been updated, created or deleted,
+such as 'compute.instance.reboot.end', 'scheduler.select_destinations.end'.
+When creating a alarm with type of "event", an event_type can be specified to
+identify the type of evernt that will trigger the alarm. The event_type field
+support fuzzy matching with wildcard. Additionally, users can also specify
+query conditions to filter specific events used to trigger the alarm.
+
+This feature was implemented with proposal event-alarm_.
+
+.. _event-alarm: https://blueprints.launchpad.net/ceilometer/+spec/event-alarm-evaluator
+
+Usage
+=====
+
+When creating an alarm of "event" type, the "event_rule" need to be specified,
+which includes an "event_type" field and a "query" field, the "event_type"
+allow users to specify a specific event type used to match the incoming events
+when evaluating alarm, and the "query" field includes a list of query
+conditions used to filter specific events when evaluating the alarm.
+
+The following is an example of event alarm rule::
+
+      "event_rule": {
+          "event_type": "compute.instance.update",
+          "query" : [
+              {
+                  "field" : "traits.instance_id",
+                  "type" : "string",
+                  "value" : "153462d0-a9b8-4b5b-8175-9e4b05e9b856",
+                  "op" : "eq",
+              },
+              {
+                  "field" : "traits.state",
+                  "type" : "string",
+                  "value" : "error",
+                  "op" : "eq",
+              },
+          ]
+      }
+
+
+Configuration
+=============
+
+To enable this functionality, config the Ceilometer to be able to publish
+events to the queue the aodh-listener service listen on. The
+*event_alarm_topic* config option of Aodh identify which messaging topic the
+aodh-listener on, the default value is "alarm.all". In Ceilometer side,
+a publisher of notifier type need to be configured in the event pipeline config
+file(event_pipeline.yaml as default), the notifier should be with a messaging
+topic same as the *event_alarm_topic* option defined. For an example::
+
+    ---
+    sources:
+        - name: event_source
+          events:
+              - "*"
+          sinks:
+              - event_sink
+    sinks:
+        - name: event_sink
+          transformers:
+          publishers:
+              - notifier://
+              - notifier://?topic=alarm.all

doc/source/index.rst

@@ -44,6 +44,7 @@ Developer Documentation
    configuration
    testing
    contributing
+   event-alarm
 
 Appendix
 ========