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:
from oslo_reports import guru_meditation_report as gmr
from manila import version
Then, register any additional sections (optional):
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:
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