Add guru meditation report for magnum

Oslo_reports enables OpenStack projects to dump Guru Meditation
Reports with useful debugging information to files or stderr.
So we introduce it into magnum.

Change-Id: Ibf78d87559f9646cc314cd064d7da4f94edc1ff7
Implements: blueprint guru-meditation-report

doc/source/gmr.rst

@@ -0,0 +1,73 @@
+..
+      Copyright (c) 2014 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
+=======================
+
+Magnum contains a mechanism whereby developers and system administrators can generate a report about the state of a running Magnum executable.  This report is called a *Guru Meditation Report* (*GMR* for short).
+
+Generating a GMR
+----------------
+
+A *GMR* can be generated by sending the *USR1* signal to any Magnum process with support (see below).  The *GMR* will then be outputted standard error for that particular process.
+
+For example, suppose that ``magnum-api`` has process id ``8675``, and was run with ``2>/var/log/magnum/magnum-api-err.log``.  Then, ``kill -USR1 8675`` will trigger the Guru Meditation report to be printed to ``/var/log/magnum/magnum-api-err.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:
+
+.. code-block:: python
+
+      from oslo_reports import guru_meditation_report as gmr
+      from nova 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 (usually ``service.server(server)`` or something similar), 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`

magnum/cmd/api.py

@@ -21,10 +21,12 @@ from wsgiref import simple_server
 
 from oslo_config import cfg
 from oslo_log import log as logging
+from oslo_reports import guru_meditation_report as gmr
 
 from magnum.api import app as api_app
 from magnum.common import service
 from magnum.i18n import _LI
+from magnum import version
 
 
 LOG = logging.getLogger(__name__)
@@ -33,6 +35,8 @@ LOG = logging.getLogger(__name__)
 def main():
     service.prepare_service(sys.argv)
 
+    gmr.TextGuruMeditation.setup_autorun(version)
+
     app = api_app.setup_app()
 
     # Create the WSGI server and start it

magnum/cmd/conductor.py

@@ -20,6 +20,7 @@ import sys
 
 from oslo_config import cfg
 from oslo_log import log as logging
+from oslo_reports import guru_meditation_report as gmr
 from oslo_service import service
 
 from magnum.common import rpc_service
@@ -31,6 +32,7 @@ from magnum.conductor.handlers import docker_conductor
 from magnum.conductor.handlers import k8s_conductor
 from magnum.i18n import _LE
 from magnum.i18n import _LI
+from magnum import version
 
 LOG = logging.getLogger(__name__)
 
@@ -38,6 +40,8 @@ LOG = logging.getLogger(__name__)
 def main():
     magnum_service.prepare_service(sys.argv)
 
+    gmr.TextGuruMeditation.setup_autorun(version)
+
     LOG.info(_LI('Starting server in PID %s') % os.getpid())
     LOG.debug("Configuration:")
     cfg.CONF.log_opt_values(LOG, std_logging.DEBUG)

requirements.txt

@@ -31,6 +31,7 @@ oslo.serialization>=1.4.0 # Apache-2.0
 oslo.service>=0.1.0 # Apache-2.0
 oslo.utils>=1.9.0 # Apache-2.0
 oslo.versionedobjects!=0.5.0,>=0.3.0
+oslo.reports>=0.1.0 # Apache-2.0
 paramiko>=1.13.0
 pbr<2.0,>=1.3
 pecan>=0.8.0