29573f8fbf
This patch updates/adds the contributor documentation to follow the guidelines of the Ussuri cycle community goal[1]. [1] https://governance.openstack.org/tc/goals/selected/ussuri/project-ptl-and-contrib-docs.html Story: #2007236 Task: #38524 Change-Id: I41b6fa23569047c8ed877902989a5ebd20c0c189
94 lines
2.9 KiB
ReStructuredText
94 lines
2.9 KiB
ReStructuredText
..
|
|
Copyright (c) 2014 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
|
|
=======================
|
|
|
|
Heat contains a mechanism whereby developers and system administrators can
|
|
generate a report about the state of a running Heat executable. This report
|
|
is called a *Guru Meditation Report* (*GMR* for short).
|
|
|
|
|
|
Generating a GMR
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
A *GMR* can be generated by sending the *USR2* signal to any Heat process with
|
|
support (see below). The *GMR* will then be outputted standard error for that
|
|
particular process.
|
|
|
|
For example, suppose that ``heat-api`` has process id ``10172``, and was run
|
|
with ``2>/var/log/heat/heat-api-err.log``. Then, ``kill -USR2 10172`` will
|
|
trigger the Guru Meditation report to be printed to
|
|
``/var/log/heat/heat-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 executable
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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
|
|
Heat version module:
|
|
|
|
.. code-block:: python
|
|
|
|
from oslo_reports import guru_meditation_report as gmr
|
|
from heat 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 ``server.start()`` 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 documentation about
|
|
:oslo.reports-doc:`oslo.reports <>`.
|