diff --git a/aodh/cmd/aodh-config-generator.conf b/aodh/cmd/aodh-config-generator.conf index 87648119f..8228a488e 100644 --- a/aodh/cmd/aodh-config-generator.conf +++ b/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 diff --git a/aodh/service.py b/aodh/service.py index 6e747709e..68efc5efb 100644 --- a/aodh/service.py +++ b/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 diff --git a/aodh/version.py b/aodh/version.py new file mode 100644 index 000000000..d9c8e01dd --- /dev/null +++ b/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') diff --git a/doc/source/contributor/gmr.rst b/doc/source/contributor/gmr.rst new file mode 100644 index 000000000..82cd5a8f4 --- /dev/null +++ b/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 `_ diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 205471f44..159769b55 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -40,6 +40,7 @@ Developer Documentation testing contributing event-alarm + gmr Appendix ======== diff --git a/releasenotes/notes/gmr-3dd0a582af010bd4.yaml b/releasenotes/notes/gmr-3dd0a582af010bd4.yaml new file mode 100644 index 000000000..34966e288 --- /dev/null +++ b/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. diff --git a/requirements.txt b/requirements.txt index cf84a229d..f5a55cba9 100644 --- a/requirements.txt +++ b/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