Merge "Introduce Guru Meditation Reports into Barbican"

barbican/cmd/keystone_listener.py

@@ -19,16 +19,18 @@ Server startup application for barbican-keystone-listener
 """
 import sys
 
+from oslo_log import log
+from oslo_reports import guru_meditation_report as gmr
+from oslo_reports import opts as gmr_opts
+from oslo_service.backend import BackendType
+from oslo_service.backend import init_backend
+from oslo_service import service
+
 from barbican.common import config
 from barbican import queue
 from barbican.queue import keystone_listener
 from barbican import version
 
-from oslo_log import log
-from oslo_service.backend import BackendType
-from oslo_service.backend import init_backend
-from oslo_service import service
-
 
 def main():
     try:
@@ -43,10 +45,12 @@ def main():
 
         # Import and configure logging.
         log.setup(CONF, 'barbican')
-
         LOG = log.getLogger(__name__)
         LOG.info("Booting up Barbican Keystone listener node...")
 
+        gmr_opts.set_defaults(CONF)
+        gmr.TextGuruMeditation.setup_autorun(version)
+
         # Queuing initialization
         queue.init(CONF)
 

barbican/cmd/retry_scheduler.py

@@ -20,14 +20,16 @@ Server startup application for barbican-retry-scheduler
 """
 import sys
 
+from oslo_log import log
+from oslo_reports import guru_meditation_report as gmr
+from oslo_reports import opts as gmr_opts
+from oslo_service import service
+
 from barbican.common import config
 from barbican import queue
 from barbican.queue import retry_scheduler
 from barbican import version
 
-from oslo_log import log
-from oslo_service import service
-
 
 def main():
     try:
@@ -40,6 +42,9 @@ def main():
         LOG = log.getLogger(__name__)
         LOG.debug("Booting up Barbican worker retry/scheduler node...")
 
+        gmr_opts.set_defaults(CONF)
+        gmr.TextGuruMeditation.setup_autorun(version)
+
         # Queuing initialization (as a client only).
         queue.init(CONF, is_server_side=False)
 

barbican/cmd/worker.py

@@ -20,16 +20,18 @@ Server startup application for barbican-worker
 """
 import sys
 
+from oslo_log import log
+from oslo_reports import guru_meditation_report as gmr
+from oslo_reports import opts as gmr_opts
+from oslo_service.backend import BackendType
+from oslo_service.backend import init_backend
+from oslo_service import service
+
 from barbican.common import config
 from barbican import queue
 from barbican.queue import server
 from barbican import version
 
-from oslo_log import log
-from oslo_service.backend import BackendType
-from oslo_service.backend import init_backend
-from oslo_service import service
-
 
 def main():
     try:
@@ -45,6 +47,9 @@ def main():
         LOG = log.getLogger(__name__)
         LOG.debug("Booting up Barbican worker node...")
 
+        gmr_opts.set_defaults(CONF)
+        gmr.TextGuruMeditation.setup_autorun(version)
+
         # Queuing initialization
         queue.init(CONF)
 

doc/source/contributor/gmr.rst

@@ -0,0 +1,88 @@
+..
+      Copyright (c) 2021 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
+=======================
+
+Barbican contains a mechanism whereby developers and system administrators can
+generate a report about the state of a running Barbican 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 Barbican process
+with support (see below).  The *GMR* will then be outputted standard error for
+that particular process.
+
+For example, suppose that ``barbican-worker`` has process id ``8675``, and
+was run with ``2>/var/log/barbican/barbican-worker.log``.  Then,
+``kill -USR1 8675`` will trigger the Guru Meditation report to be printed to
+``/var/log/barbican/barbican-worker.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 Barbican version module:
+
+.. code-block:: python
+
+      from oslo_reports import guru_meditation_report as gmr
+      from barbican 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
+about oslo.reports:
+`oslo.reports <https://docs.openstack.org/oslo.reports/latest/>`_

doc/source/contributor/index.rst

@@ -28,6 +28,7 @@ When you're ready to dive deeper in to barbican take a look at:
    dataflow.rst
    dependencies.rst
    database_migrations.rst
+   gmr.rst
    microversions.rst
    plugin/index.rst
    testing.rst

etc/oslo-config-generator/barbican.conf

@@ -17,5 +17,6 @@ namespace = oslo.messaging
 namespace = oslo.middleware.cors
 namespace = oslo.middleware.healthcheck
 namespace = oslo.middleware.http_proxy_to_wsgi
+namespace = oslo.reports
 namespace = oslo.policy
 namespace = oslo.versionedobjects

releasenotes/notes/gmr-9811bbc294bb5535.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Barbican now supports generation of Guru Meditation Reports using
+    oslo.reports libary.

requirements.txt

@@ -14,6 +14,7 @@ oslo.messaging>=14.1.0 # Apache-2.0
 oslo.middleware>=3.31.0 # Apache-2.0
 oslo.log>=4.3.0 # Apache-2.0
 oslo.policy>=4.5.0 # Apache-2.0
+oslo.reports>=1.18.0 # Apache-2.0
 oslo.serialization!=2.19.1,>=2.18.0 # Apache-2.0
 oslo.service[threading]>=4.2.0 # Apache-2.0
 oslo.upgradecheck>=1.3.0 # Apache-2.0