diff --git a/doc/source/devref/guru_meditation_report.rst b/doc/source/devref/guru_meditation_report.rst new file mode 100644 index 0000000000..26a27c6746 --- /dev/null +++ b/doc/source/devref/guru_meditation_report.rst @@ -0,0 +1,119 @@ +.. + Copyright (c) 2017 Fiberhome Telecommunication Technologies Co.,LTD + 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 +======================= + +Manila contains a mechanism whereby developers and system administrators can +generate a report about the state of a running Manila executable. +This report is called a *Guru Meditation Report* (*GMR* for short). + +Generating a GMR +---------------- + +A *GMR* can be generated by sending the *SIGUSR1/SIGUSR2* signal to any Manila +process with support (see below). +The *GMR* will then output to standard error for that particular process. + +For example, suppose that ``manila-api`` has process id ``8675``, and was run +with ``2>/var/log/manila/manila-api-err.log``. +Then, ``kill -SIGUSR1 8675`` will trigger the Guru Meditation report to be +printed to ``/var/log/manila/manila-api-err.log``. + +It could save these reports to a well known directory for later analysis by +the sysadmin or automated bug analysis tools. To configure *GMR* you have to +add the following section to manila.conf: + +[oslo_reports] +log_dir = '/path/to/logs/dir' + +There is other way to trigger a generation of report, user should add +a configuration in Manila'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'] + +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 ``manila-api`` was run with +``2>/var/log/manila/manila-api-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/manila/manila-api-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 + +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.reports), as well as the +Manila version module: + +.. code-block:: python + + from oslo_reports import guru_meditation_report as gmr + from manila 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/devref/index.rst b/doc/source/devref/index.rst index 40b6ba89a9..2bdc462151 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -34,6 +34,7 @@ Programming HowTos and Tutorials documenting_your_work adding_release_notes commit_message_tags + guru_meditation_report Background Concepts for manila diff --git a/manila/cmd/api.py b/manila/cmd/api.py index b72343d126..07c6f5eb2c 100644 --- a/manila/cmd/api.py +++ b/manila/cmd/api.py @@ -25,6 +25,8 @@ import sys 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 manila import i18n i18n.enable_lazy() @@ -39,12 +41,14 @@ CONF = cfg.CONF def main(): log.register_options(CONF) + gmr_opts.set_defaults(CONF) CONF(sys.argv[1:], project='manila', version=version.version_string()) config.verify_share_protocols() log.setup(CONF, "manila") utils.monkey_patch() + gmr.TextGuruMeditation.setup_autorun(version, conf=CONF) launcher = service.process_launcher() server = service.WSGIService('osapi_share') launcher.launch_service(server, workers=server.workers or 1) diff --git a/manila/cmd/data.py b/manila/cmd/data.py index 8519046425..9b232a53f5 100644 --- a/manila/cmd/data.py +++ b/manila/cmd/data.py @@ -23,6 +23,8 @@ import sys 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 manila import i18n i18n.enable_lazy() @@ -36,10 +38,12 @@ CONF = cfg.CONF def main(): log.register_options(CONF) + gmr_opts.set_defaults(CONF) CONF(sys.argv[1:], project='manila', version=version.version_string()) log.setup(CONF, "manila") utils.monkey_patch() + gmr.TextGuruMeditation.setup_autorun(version, conf=CONF) server = service.Service.create(binary='manila-data') service.serve(server) service.wait() diff --git a/manila/cmd/scheduler.py b/manila/cmd/scheduler.py index 04f6996798..109b167399 100644 --- a/manila/cmd/scheduler.py +++ b/manila/cmd/scheduler.py @@ -25,6 +25,8 @@ import sys 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 manila import i18n i18n.enable_lazy() @@ -38,10 +40,12 @@ CONF = cfg.CONF def main(): log.register_options(CONF) + gmr_opts.set_defaults(CONF) CONF(sys.argv[1:], project='manila', version=version.version_string()) log.setup(CONF, "manila") utils.monkey_patch() + gmr.TextGuruMeditation.setup_autorun(version, conf=CONF) server = service.Service.create(binary='manila-scheduler') service.serve(server) service.wait() diff --git a/manila/cmd/share.py b/manila/cmd/share.py index 49ca96b720..2b62192c9e 100644 --- a/manila/cmd/share.py +++ b/manila/cmd/share.py @@ -24,6 +24,8 @@ import sys 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 manila import i18n i18n.enable_lazy() @@ -38,10 +40,12 @@ CONF = cfg.CONF def main(): log.register_options(CONF) + gmr_opts.set_defaults(CONF) CONF(sys.argv[1:], project='manila', version=version.version_string()) log.setup(CONF, "manila") utils.monkey_patch() + gmr.TextGuruMeditation.setup_autorun(version, conf=CONF) launcher = service.process_launcher() if CONF.enabled_share_backends: for backend in CONF.enabled_share_backends: diff --git a/releasenotes/notes/guru-meditation-support-7872da69f529a6c2.yaml b/releasenotes/notes/guru-meditation-support-7872da69f529a6c2.yaml new file mode 100644 index 0000000000..2dba798b07 --- /dev/null +++ b/releasenotes/notes/guru-meditation-support-7872da69f529a6c2.yaml @@ -0,0 +1,7 @@ +--- +features: + - Adds support to generate Guru Meditation Reports(GMR) for manila + services. GMR provides useful debugging information that can be + used to obtain an accurate view on the current live state of the + system. For example, what threads are running, what configuration + parameters are in effect, and more. diff --git a/requirements.txt b/requirements.txt index 615c8c855c..f37c4eb441 100644 --- a/requirements.txt +++ b/requirements.txt @@ -19,6 +19,7 @@ oslo.log>=3.22.0 # Apache-2.0 oslo.messaging!=5.25.0,>=5.24.2 # Apache-2.0 oslo.middleware>=3.27.0 # Apache-2.0 oslo.policy>=1.23.0 # Apache-2.0 +oslo.reports>=0.6.0 # Apache-2.0 oslo.rootwrap>=5.0.0 # Apache-2.0 oslo.serialization>=1.10.0 # Apache-2.0 oslo.service>=1.10.0 # Apache-2.0