diff --git a/doc/source/gmr.rst b/doc/source/gmr.rst index 44fb90d1c4..577b77f0f2 100644 --- a/doc/source/gmr.rst +++ b/doc/source/gmr.rst @@ -16,31 +16,43 @@ Guru Meditation Reports ======================= -Magnum contains a mechanism whereby developers and system administrators can generate a report about the state of a running Magnum executable. This report is called a *Guru Meditation Report* (*GMR* for short). +Magnum contains a mechanism whereby developers and system administrators can +generate a report about the state of a running Magnum 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 Magnum process with support (see below). The *GMR* will then be outputted standard error for that particular process. +A *GMR* can be generated by sending the *USR1* signal to any Magnum process +with support (see below). The *GMR* will then be outputted as standard error +for that particular process. -For example, suppose that ``magnum-api`` has process id ``8675``, and was run with ``2>/var/log/magnum/magnum-api-err.log``. Then, ``kill -USR1 8675`` will trigger the Guru Meditation report to be printed to ``/var/log/magnum/magnum-api-err.log``. +For example, suppose that ``magnum-api`` has process id ``8675``, and was run +with ``2>/var/log/magnum/magnum-api-err.log``. Then, ``kill -USR1 8675`` will +trigger the Guru Meditation report to be printed to +``/var/log/magnum/magnum-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: +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 + Shows information about the package to which this process belongs, including + version informations. Threads - Shows stack traces and thread ids for each of the threads within this process + 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) + 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 + Lists all the configuration options currently accessible via the CONF object + for the current process. Adding Support for GMRs to New Executables ------------------------------------------ @@ -61,7 +73,8 @@ 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: +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 @@ -70,4 +83,6 @@ Finally (under main), before running the "main loop" of the executable (usually 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 under :mod:`oslo.reports` +As mentioned above, additional sections can be added to the GMR for a +particular executable. For more information, see the inline documentation +under :mod:`oslo.reports`