compress events notes

this patch moves some event related topics out of main TOC and into
events section. this patch does not remove any information.
removal/cleanup of information and restructing of toc will be done
in future patch

Change-Id: Ic522b9e64c43fbdb5769fd9956cb266571615ecf

doc/source/events.rst

@@ -59,13 +59,16 @@ traits
     The event's Traits contain most of the details of the event. Traits are
     typed, and can be strings, ints, floats, or datetimes.
 
+raw
+    (Optional) Mainly for auditing purpose, the full notification message
+    can be stored (unindexed) for future evaluation.
 
 Events from Notifications
 =========================
 
 Events are primarily created via the notifications system in OpenStack.
 OpenStack systems, such as Nova, Glance, Neutron, etc. will emit
-notifications in a JSON format to message queue when some notable action is
+notifications in a JSON format to the message queue when some notable action is
 taken by that system. Ceilometer will consume such notifications from the
 message queue, and process them.
 
@@ -103,7 +106,7 @@ projects (mostly Nova) using empty string for null dates.)
 
 If the definitions file is not present, a warning will be logged, but an empty
 set of definitions will be assumed. By default, any notifications that
-do not have an event definition in the definitions file for them will be
+do not have a corresponding event definition in the definitions file will be
 converted to events with a set of minimal, default traits.  This can be
 changed by setting the flag drop_unmatched_notifications_ in the
 ceilometer.conf file. If this is set to True, then any notifications
@@ -267,3 +270,18 @@ added. If the plugin returns anything other than *None*, the trait's value
 will be set from whatever the plugin returned (coerced to the appropriate type
 for the trait).
 
+Building Notifications
+======================
+
+In general, the payload format OpenStack services emit could be described as
+the Wild West. The payloads are often arbitrary data dumps at the time of
+the event which is often susceptible to change. To make consumption easier,
+the Ceilometer team offers two proposals: CADF_, an open, cloud standard
+which helps model cloud events and the PaaS Event Format.
+
+.. toctree::
+   :maxdepth: 1
+
+   format
+
+.. _CADF: http://docs.openstack.org/developer/pycadf/

doc/source/format.rst

@@ -4,6 +4,9 @@
 
  http://creativecommons.org/licenses/by/3.0/legalcode
 
+
+.. _paas_event_format:
+
 =================
 PaaS Event Format
 =================
@@ -211,7 +214,6 @@ guideline for PaaS service developers:
     as in the specifications.
     **Audit period timestamps** are not currently enforced against the audit period.
 
-=============
 Sample Events
 =============
 
@@ -337,4 +339,3 @@ event.
                 "state_description": "happy DNS"
                 }
     }
-

doc/source/index.rst

@@ -49,7 +49,6 @@ Table of contents
    architecture
    measurements
    events
-   format
    install/index
    configuration
    webapi/index