Merge "Add spec for adding statistics gathering API for loadbalancer"

specs/version1/stats_api.rst

@@ -0,0 +1,167 @@
+..
+     This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+=============================================
+Add statistics gathering API for loadbalancer
+=============================================
+
+https://blueprints.launchpad.net/octavia/+spec/stats-support
+
+Problem description
+===================
+Currently, Octavia does not support the gathering of loadbalancer statistics.
+This causes inconsistencies between the Octavia and Neutron-LBaaS APIs.
+Another point is that the statistics data we get from the Octavia API for the
+listener only reflects the first record for the listener in the Octavia
+database, since we're supporting more topologies than SINGLE, this needs to
+be to fixed too.
+
+Proposed change
+===============
+Add one more data 'request_errors' to indicate the number of request errors
+for each listener, we can get this data from the stats of haproxy 'ereq'.
+
+Add a new module 'stats' to octavia.common with a class 'StatsMixin' to
+do the actual statistics calculation for both listener and loadbalancer. Make
+the mixin class as a new base class for
+octavia.api.v1.controllers.listener_statistics.ListenerStatisticsController,
+to make sure we get correct stats from Octavia API.
+
+Add a new module 'loadbalancer_statistics' to octavia.api.v1.controllers with
+a class LoadbalancerStatisticsController to provide a new REST API
+for gathering statistics at the loadbalancer level.
+
+Use evenstream to serialize the statistics messages from the octavia to
+neutron-lbaas via oslo_messaging, to keep consistent with neutron-lbaas API.
+
+Alternatives
+------------
+Update the 'stats' method in neutron-lbaas for octavia driver, allow the
+neutron-lbaas to get stats from octavia through REST API request, to keep
+consistent with neutron-lbaas API.
+
+Data model impact
+-----------------
+One new column for table listener_statistics will be introduced to represent
+request errors:
+
+    +--------------------+-------------+------+-----+---------+-------+
+    | Field              | Type        | Null | Key | Default | Extra |
+    +--------------------+-------------+------+-----+---------+-------+
+    | request_errors     | bigint(20)  | NO   |     | NULL    |       |
+    +--------------------+-------------+------+-----+---------+-------+
+
+REST API impact
+---------------
+
+Add 'request_errors' in the response of list listener statistics:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Example List listener statistics: JSON response**
+
+.. code::
+
+    {
+        "listener": {
+            "bytes_in": 0,
+            "bytes_out": 0,
+            "active_connections": 0,
+            "total_connections": 0,
+            "request_errors": 0
+        }
+    }
+
+Add a new API to list loadbalancer statistics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Lists loadbalancer statistics.
+
+    +----------------+------------------------------------------------+
+    | Request Type   | ``GET``                                        |
+    +----------------+------------------------------------------------+
+    | Endpoint       | ``URL/v1/loadbalancers/{lb_id}/stats``         |
+    +----------------+---------+--------------------------------------+
+    |                | Success | 200                                  |
+    | Response Codes +---------+--------------------------------------+
+    |                | Error   | 401, 404, 500                        |
+    +----------------+---------+--------------------------------------+
+
+**Example List loadbalancer statistics: JSON response**
+
+
+.. code::
+
+    {
+        "loadbalancer": {
+            "bytes_in": 0,
+            "bytes_out": 0,
+            "active_connections": 0,
+            "total_connections": 0,
+            "request_errors": 0,
+            "listeners": [{
+                "id": "uuid"
+                "bytes_in": 0,
+                "bytes_out": 0,
+                "active_connections": 0,
+                "total_connections": 0,
+                "request_errors": 0,
+            }]
+        }
+    }
+
+Security impact
+---------------
+None
+
+Notifications impact
+--------------------
+None
+
+Other end user impact
+---------------------
+None
+
+Performance Impact
+------------------
+None
+
+Other deployer impact
+---------------------
+None
+
+Developer impact
+----------------
+None
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+li, chen <shchenli@cn.ibm.com>
+
+Work Items
+----------
+* Extend current stats collection for listener amphora
+* Add module 'stats'
+* Add new API for gathering statistics at the loadbalancer level
+* Update stats to neutron database
+
+Dependencies
+============
+None
+
+Testing
+=======
+Function tests with tox.
+
+Documentation Impact
+====================
+Changes shall be introduced to the octavia APIs: see [1]
+
+References
+==========
+[1] http://docs.openstack.org/developer/octavia/api/octaviaapi.html