diff --git a/barbican/cmd/keystone_listener.py b/barbican/cmd/keystone_listener.py index 84b11a035..1b730e438 100644 --- a/barbican/cmd/keystone_listener.py +++ b/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) diff --git a/barbican/cmd/retry_scheduler.py b/barbican/cmd/retry_scheduler.py index 07a25ab93..0f07425cd 100644 --- a/barbican/cmd/retry_scheduler.py +++ b/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) diff --git a/barbican/cmd/worker.py b/barbican/cmd/worker.py index 1ca087b6c..f4e4c92d0 100644 --- a/barbican/cmd/worker.py +++ b/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) diff --git a/doc/source/contributor/gmr.rst b/doc/source/contributor/gmr.rst new file mode 100644 index 000000000..cba6ca558 --- /dev/null +++ b/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 `_ diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 1ebfca8ab..0aafec542 100644 --- a/doc/source/contributor/index.rst +++ b/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 diff --git a/etc/oslo-config-generator/barbican.conf b/etc/oslo-config-generator/barbican.conf index 4f050349e..7374b5778 100644 --- a/etc/oslo-config-generator/barbican.conf +++ b/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 diff --git a/releasenotes/notes/gmr-9811bbc294bb5535.yaml b/releasenotes/notes/gmr-9811bbc294bb5535.yaml new file mode 100644 index 000000000..8fcc7e533 --- /dev/null +++ b/releasenotes/notes/gmr-9811bbc294bb5535.yaml @@ -0,0 +1,5 @@ +--- +features: + - | + Barbican now supports generation of Guru Meditation Reports using + oslo.reports libary. diff --git a/requirements.txt b/requirements.txt index a5b25d90b..7968407d8 100644 --- a/requirements.txt +++ b/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