Introduce Guru to Zaqar

Guru is a mechanism whereby developers
and system administrators can generate
a report about the state of a running
Zaqar executable.

This report is called a *Guru Meditation Report*

This mechanism will help developer or operator
to fix issues in (production) deployments without
stopping Zaqar service.

Implements: blueprint introduce-guru-to-zaqar
Change-Id: I72885be396be7eb0a9dd8fd564d706a8351b02c6

doc/source/devref/gmr.rst

@@ -0,0 +1,87 @@
+..
+      Copyright (c) 2017 OpenStack Foundation
+      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.
+
+=======================
+Guru Meditation Reports
+=======================
+
+Zaqar contains a mechanism whereby developers and system administrators can
+generate a report about the state of a running Zaqar executable.
+This report is called a *Guru Meditation Report* (*GMR* for short).
+
+Generating a GMR
+----------------
+
+For wsgi and websocket mode, a *GMR* can be generated by sending the *USR2*
+signal to any Zaqar process with support (see below).
+The *GMR* will then be outputted standard error for that particular process.
+
+For example, suppose that ``zaqar-server`` has process id ``8675``, and was
+run with ``2>/var/log/zaqar/zaqar-server-err.log``.
+Then, ``kill -USR2 8675`` will trigger the Guru Meditation report to be
+printed to ``/var/log/zaqar/zaqar-server-err.log``.
+
+For uwsgi mode, user should add a configuration in Zaqar's conf file::
+
+    [oslo_reports]
+    file_event_handler=['The path to a file to watch for changes to trigger '
+                        'the reports, instead of signals. Setting this option '
+                        'disables the signal trigger for the reports.']
+    file_event_handler_interval=['How many seconds to wait between polls when '
+                                 'file_event_handler is set, default value '
+                                 'is 1']
+
+For example, you can specify "file_event_handler=/tmp/guru_report" and
+"file_event_handler_interval=1" in Zaqar's conf file.
+
+A *GMR* can be generated by "touch"ing the file which was specified in
+file_event_handler. The *GMR* will then output to standard error for
+that particular process.
+
+For example, suppose that ``zaqar-server`` was run with
+``2>/var/log/zaqar/zaqar-server-err.log``, and the file path is
+``/tmp/guru_report``.
+Then, ``touch /tmp/guru_report`` will trigger the Guru Meditation report to be
+printed to ``/var/log/zaqar/zaqar-server-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
+
+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
+about oslo.reports:
+`oslo.reports <http://docs.openstack.org/developer/oslo.reports/>`_

doc/source/index.rst

@@ -208,6 +208,14 @@ Internal API reference
 
    api/autoindex
 
+Guru Meditation Reports
+=======================
+
+.. toctree::
+   :maxdepth: 1
+
+   devref/gmr
+
 Indices and tables
 ------------------
 

etc/oslo-config-generator/zaqar.conf

@@ -16,3 +16,4 @@ namespace = keystonemiddleware.auth_token
 namespace = oslo.cache
 namespace = oslo.messaging
 namespace = osprofiler
+namespace = oslo.reports

releasenotes/notes/introduce-guru-to-zaqar-ac7b51c764503829.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - Introduce Guru to Zaqar. Guru is a mechanism whereby developers and system
+    administrators can generate a report about the state of a running Zaqar
+    executable. This report is called a *Guru Meditation Report*. Now Guru can
+    support wsgi, websocket and uwsgi modes all.

requirements.txt

@@ -20,6 +20,7 @@ oslo.context>=2.12.0 # Apache-2.0
 oslo.i18n>=2.1.0 # Apache-2.0
 oslo.log>=3.11.0 # Apache-2.0
 oslo.messaging>=5.14.0 # Apache-2.0
+oslo.reports>=0.6.0 # Apache-2.0
 oslo.serialization>=1.10.0 # Apache-2.0
 oslo.utils>=3.18.0 # Apache-2.0
 oslo.policy>=1.17.0 # Apache-2.0

zaqar/cmd/server.py

@@ -16,10 +16,13 @@ import os
 
 from oslo_config import cfg
 from oslo_log import log
+from oslo_reports import guru_meditation_report as gmr
+from oslo_reports import opts as gmr_opts
 
 from zaqar import bootstrap
 from zaqar.common import cli
 from zaqar.common import configs
+from zaqar import version
 
 # NOTE(eggmaster): define command line options for zaqar-server
 _CLI_OPTIONS = (
@@ -33,6 +36,7 @@ _CLI_OPTIONS = (
 def run():
     # Use the global CONF instance
     conf = cfg.CONF
+    gmr_opts.set_defaults(conf)
     # NOTE(eggmaster): register command line options for zaqar-server
     conf.register_cli_opts(_CLI_OPTIONS)
     log.register_options(conf)
@@ -46,6 +50,8 @@ def run():
     conf(project='zaqar', prog='zaqar-server')
     log.setup(conf, 'zaqar')
 
+    gmr.TextGuruMeditation.setup_autorun(version, conf=conf)
+
     server = bootstrap.Bootstrap(conf)
 
     # The following code is to daemonize zaqar-server to avoid

zaqar/transport/wsgi/app.py

@@ -28,15 +28,21 @@ to the WSGI app when it is called from other apps.
 
 from oslo_config import cfg
 from oslo_log import log
+from oslo_reports import guru_meditation_report as gmr
+from oslo_reports import opts as gmr_opts
 
 from zaqar import bootstrap
+from zaqar import version
 
 # Use the global CONF instance
 conf = cfg.CONF
+gmr_opts.set_defaults(conf)
 log.register_options(conf)
 conf(project='zaqar', prog='zaqar-queues', args=[])
 log.setup(conf, 'zaqar')
 
+gmr.TextGuruMeditation.setup_autorun(version, conf=conf)
+
 boot = bootstrap.Bootstrap(conf)
 conf.drivers.transport = 'wsgi'
 application = boot.transport.app

zaqar/version.py

@@ -17,6 +17,7 @@ import pbr.version
 
 
 version_info = pbr.version.VersionInfo('zaqar')
+version_string = version_info.version_string
 
 
 def verify_sha(expected):