Merge "Introduce Guru Meditation Reports into Aodh"

aodh/cmd/aodh-config-generator.conf

@@ -9,4 +9,5 @@ namespace = oslo.middleware.cors
 namespace = oslo.middleware.healthcheck
 namespace = oslo.middleware.http_proxy_to_wsgi
 namespace = oslo.policy
+namespace = oslo.reports
 namespace = keystonemiddleware.auth_token

aodh/service.py

@@ -22,12 +22,14 @@ from oslo_db import options as db_options
 import oslo_i18n
 from oslo_log import log
 from oslo_policy import opts as policy_opts
+from oslo_reports import guru_meditation_report as gmr
 from oslo_utils import importutils
 
 from aodh.conf import defaults
 from aodh import keystone_client
 from aodh import messaging
 from aodh import profiler
+from aodh import version
 
 profiler_opts = importutils.try_import('osprofiler.opts')
 
@@ -96,10 +98,17 @@ def prepare_service(argv=None, config_files=None):
     keystone_client.register_keystoneauth_opts(conf)
 
     conf(argv, project='aodh', validate_default_values=True,
-         default_config_files=config_files)
+         default_config_files=config_files,
+         version=version.version_info.version_string())
 
     ka_loading.load_auth_from_conf_options(conf, "service_credentials")
     log.setup(conf, 'aodh')
+
+    # NOTE(tkajinam): guru cannot run with service under apache daemon, so when
+    # aod-api running with mod_wsgi, the argv is [], we don't start guru.
+    if argv:
+        gmr.TextGuruMeditation.setup_autorun(version)
+
     profiler.setup(conf)
     messaging.setup()
     return conf

aodh/version.py

@@ -0,0 +1,17 @@
+#
+#    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('aodh')

doc/source/contributor/gmr.rst

@@ -0,0 +1,89 @@
+..
+      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
+=======================
+
+Aodh contains a mechanism whereby developers and system administrators can
+generate a report about the state of a running Aodh 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 Aodh process with
+support (see below).  The *GMR* will then be outputted standard error for that
+particular process.
+
+For example, suppose that ``aodh-listener`` has process id ``8675``, and
+was run with ``2>/var/log/aodh/aodh-listener.log``.  Then, ``kill -USR1 8675``
+will trigger the Guru Meditation report to be printed to
+``/var/log/aodh/aodh-listener.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 (currently residing in oslo-incubator), as well as the
+Aodh version module:
+
+.. code-block:: python
+
+      from oslo_reports import guru_meditation_report as gmr
+      from aodh 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

@@ -40,6 +40,7 @@ Developer Documentation
    testing
    contributing
    event-alarm
+   gmr
 
 Appendix
 ========

releasenotes/notes/gmr-3dd0a582af010bd4.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Aodh now supports generation of Guru Meditation Reports using oslo.reports
+    library. Each service prints a report output when it receives SIGUSR1.

requirements.txt

@@ -14,6 +14,7 @@ oslo.config>=6.8.0 # Apache-2.0
 oslo.context>=2.22.0 # Apache-2.0
 oslo.i18n>=1.5.0 # Apache-2.0
 oslo.log>=4.3.0 # Apache-2.0
+oslo.reports>=1.18.0 # Apache-2.0
 oslo.policy>=3.7.0 # Apache-2.0
 oslo.upgradecheck>=1.3.0 # Apache-2.0
 PasteDeploy>=1.5.0