Implement Guru meditation reports

Guru can log runtime configuration of a given process, along with
thread status and greenthread status. It greatly help check the
process runtime status.

The usage is simple:
kill -USR2 {process-id}

In dragonflow, you can show the reports of df-controller,
df-publisher, df-l3-agent, and the coming df-metadata-service.

The description is as follows:
https://wiki.openstack.org/wiki/GuruMeditationReport

Closes-Bug: #1568220
Change-Id: I24048e1018ba3710b7a7476ca1dd83a5ae38894a

doc/source/gmr.rst

@@ -0,0 +1,80 @@
+..
+      Copyright (c) 2016 OpenStack Foundation
+
+      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.
+
+Guru Meditation Reports
+=======================
+
+Dragonflow contains a mechanism whereby developers and system administrators can generate a report about
+the state of a running Dragonflow executable.
+This report is called a *Guru Meditation Report* (*GMR* for short).
+
+Generating a GMR
+----------------
+
+A *GMR* can be generated by sending the *USR2* signal to any Dragonflow process with support (see below).
+The *GMR* will then be outputted standard error for that particular process.
+
+For example, suppose that ``df-local-controller`` has process id ``2525``, and was run with
+``2>/var/log/dragonflow/df-controller.log``.  Then, ``kill -USR2 2525`` will trigger the Guru Meditation
+report to be printed to ``/var/log/dragonflow/df-controller.log``.
+
+Structure of a GMR
+------------------
+
+The *GMR* is designed to be extensible; any particular executable may add its own sections. However,
+the base *GMR* consists of several sections:
+
+Package
+  Shows information about the package to which this process belongs, including version information
+
+Threads
+  Shows stack traces and thread ids for each of the threads within this process
+
+Green Threads
+  Shows stack traces for each of the green threads within this process (green threads don't have thread ids)
+
+Configuration
+  Lists all the configuration options currently accessible via the CONF object for the current process
+
+Adding Support for GMRs to New Executables
+------------------------------------------
+
+Adding support for a *GMR* to a given executable is fairly easy.
+
+First import the module, as well as the Dragonflow version module:
+
+.. code-block:: python
+
+      from oslo_reports import guru_meditation_report as gmr
+      from dragonflow import version
+
+Then, register any additional sections (optional):
+
+.. code-block:: python
+
+      TextGuruMeditation.register_section('Some Special Section',
+                                          some_section_generator)
+
+Finally (under main), before running the "main loop" of the executable, register the *GMR* hook:
+
+.. code-block:: python
+
+      TextGuruMeditation.setup_autorun(version)
+
+Extending the GMR
+-----------------
+
+As mentioned above, additional sections can be added to the GMR for a particular executable.
+For more information, see the inline documentation under :mod:`oslo.reports`

doc/source/index.rst

@@ -20,6 +20,7 @@ Contents:
    pluggable_pubsub
    pipeline
    containers
+   gmr
    usage
    features
    contributing

doc/source/readme.rst

@@ -4,7 +4,7 @@ Keep in mind that Dragonflow is still in beta.
 Prerequisites
 ------------
 
-1) OVS 2.4.0
+1) Open vSwitch 2.5.0
 
 Quick Installation
 -------------------
@@ -29,9 +29,9 @@ Quick Installation
 
    enable_service df-ext-services
 
-   enable_service q-svc
+   enable_service df-l3-agent
 
-   enable_service q-l3
+   enable_service q-svc
 
    disable_service q-agt
 

dragonflow/cmd/__init__.py

@@ -0,0 +1,28 @@
+# All Rights Reserved.
+#
+#    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.
+
+import logging as sys_logging
+
+from oslo_reports import guru_meditation_report as gmr
+
+from dragonflow import version
+
+# During the call to gmr.TextGuruMeditation.setup_autorun(), Guru Meditation
+# Report tries to start logging. Set a handler here to accommodate this.
+logger = sys_logging.getLogger(None)
+if not logger.handlers:
+    logger.addHandler(sys_logging.StreamHandler())
+
+_version_string = version.version_info.release_string()
+gmr.TextGuruMeditation.setup_autorun(version=_version_string)

dragonflow/version.py

@@ -0,0 +1,17 @@
+#    Copyright 2016 OpenStack Foundation
+#
+#    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.
+
+import pbr.version
+
+version_info = pbr.version.VersionInfo('dragonflow')

requirements.txt

@@ -14,4 +14,5 @@ alembic>=0.8.4 # MIT
 neutron-lib>=0.2.0  # Apache-2.0
 oslo.config>=3.10.0 # Apache-2.0
 oslo.db>=4.1.0 # Apache-2.0
+oslo.reports>=0.6.0 # Apache-2.0
 redis>=2.10.0 # MIT