Add Event and Trait API to document

WebAPI has nothing about Event and Trait API, this patch fix it.

Note: sphinxcontrib-pecanwsme has a bug, cannot handle the issue that
there is an unexposed path in URL. This patch exposes
EventTypesController.get_one as a workaround.

Change-Id: If881d674ee71d55edc22db85a53ba972b5858be5
Closes-Bug: #1388514

ceilometer/api/controllers/v2.py

@@ -2310,6 +2310,13 @@ class EventQuery(Query):
                                              self._get_value_as_type(),
                                              self.type)
 
+    @classmethod
+    def sample(cls):
+        return cls(field="event_type",
+                   type="string",
+                   op="eq",
+                   value="compute.instance.create.start")
+
 
 class Trait(_Base):
     """A Trait associated with an event."""
@@ -2374,12 +2381,15 @@ class Event(_Base):
     def sample(cls):
         return cls(
             event_type='compute.instance.update',
-            generated='2013-11-11T20:00:00',
+            generated=datetime.datetime(2015, 1, 1, 12, 30, 59, 123456),
             message_id='94834db1-8f1b-404d-b2ec-c35901f1b7f0',
             traits={
-                'request_id': 'req-4e2d67b8-31a4-48af-bb2f-9df72a353a72',
+                Trait(name='request_id',
-                'service': 'conductor.tem-devstack-01',
+                      value='req-4e2d67b8-31a4-48af-bb2f-9df72a353a72'),
-                'tenant_id': '7f13f2b17917463b9ee21aa92c4b36d6'
+                Trait(name='service',
+                      value='conductor.tem-devstack-01'),
+                Trait(name='tenant_id',
+                      value='7f13f2b17917463b9ee21aa92c4b36d6')
             }
         )
 
@@ -2465,8 +2475,13 @@ class EventTypesController(rest.RestController):
 
     traits = TraitsController()
 
-    @pecan.expose()
+    @requires_admin
+    @wsme_pecan.wsexpose(None, wtypes.text)
     def get_one(self, event_type):
+        """Unused API, will always return 404.
+
+        :param event_type: A event type
+        """
         pecan.abort(404)
 
     @requires_admin

doc/source/webapi/v2.rst

@@ -106,8 +106,30 @@ Alarms
 .. autotype:: ceilometer.api.controllers.v2.AlarmChange
    :members:
 
+Events and Traits
+=================
+
+.. rest-controller:: ceilometer.api.controllers.v2:EventTypesController
+   :webprefix: /v2/event_types
+
+.. rest-controller:: ceilometer.api.controllers.v2:TraitsController
+   :webprefix: /v2/event_types/(event_type)/traits
+
+.. rest-controller:: ceilometer.api.controllers.v2:EventsController
+   :webprefix: /v2/events
+
+.. autotype:: ceilometer.api.controllers.v2.Event
+   :members:
+
+.. autotype:: ceilometer.api.controllers.v2.Trait
+   :members:
+
+.. autotype:: ceilometer.api.controllers.v2.TraitDescription
+   :members:
+
 Filtering Queries
 =================
+
 Ceilometer's REST API currently supports two types of queries. The Simple
 Query functionality provides simple filtering on several fields of the
 *Sample* type. Complex Query provides the possibility to specify queries
@@ -127,6 +149,7 @@ all other fields.
 
 Simple Query
 ++++++++++++
+
 Many of the endpoints above accept a query filter argument, which
 should be a list of Query data structures. Whatever the endpoint you
 want to apply a filter on, you always filter on the fields of the *Sample*
@@ -137,8 +160,22 @@ field of *Sample*).
 .. autotype:: ceilometer.api.controllers.v2.Query
    :members:
 
+Event Query
++++++++++++
+
+Event query is similar to simple query, its type EventQuery is actually
+a subclass of Query, so EventQuery has every attribute Query has.
+But there are some differences. If a field is one of the following:
+event_type, message_id, start_timestamp, end_timestamp, then this field
+will be applied on event, otherwise it will be treated as trait name and
+applied on trait.
+
+.. autotype:: ceilometer.api.controllers.v2.EventQuery
+   :members:
+
 Complex Query
 +++++++++++++
+
 The filter expressions of the Complex Query feature operate on the fields
 of *Sample*, *Alarm* and *AlarmChange*. The following comparison operators are
 supported: *=*, *!=*, *<*, *<=*, *>*, *>=* and *in*; and the following logical
@@ -183,9 +220,9 @@ Links
 API and CLI query examples
 ==========================
 
-
 CLI Queries
 +++++++++++
+
 Ceilometer CLI Commands::
 
      $ ceilometer --debug --os-username <username_here> --os-password <password_here> --os-auth-url http://localhost:5000/v2.0/ --os-tenant-name admin  meter-list
@@ -195,6 +232,7 @@ Ceilometer CLI Commands::
 
 API Queries
 +++++++++++
+
 Ceilometer API calls:
 
 .. note:: To successfully query the Ceilometer you must first get a project-specific token from the Keystone service and add it to any API calls that you execute against that project. See the `OpenStack credentials documentation <http://docs.openstack.org/api/quick-start/content/index.html#getting-credentials-a00665>`_ for additional details.
@@ -245,7 +283,6 @@ the CPU utilization for a given instance (identified by *resource_id*)::
 
 .. note:: If any of the requested aggregates are not supported by the storage driver, a HTTP 400 error code will be returned along with an appropriate error message.
 
-
 JSON based example::
 
      curl -X GET -H "X-Auth-Token: <inserttokenhere>" -H "Content-Type: application/json"