oslo_reports package

Subpackages

Submodules

oslo_reports.guru_meditation_report module

Provides Guru Meditation Report

This module defines the actual OpenStack Guru Meditation Report class.

This can be used in the OpenStack command definition files. For example, in a nova command module (under nova/cmd):

from oslo_config import cfg
from oslo_log import log as oslo_logging
from oslo_reports import opts as gmr_opts
from oslo_reports import guru_meditation_report as gmr

CONF = cfg.CONF
# maybe import some options here...

def main():
    oslo_logging.register_options(CONF)
    gmr_opts.set_defaults(CONF)

    CONF(sys.argv[1:], default_config_files=['myapp.conf'])
    oslo_logging.setup(CONF, 'myapp')

    gmr.TextGuruMeditation.register_section('Some Special Section',
                                        special_section_generator)
    gmr.TextGuruMeditation.setup_autorun(version_object, conf=CONF)

    server = service.Service.create(binary='some-service',
                                    topic=CONF.some_service_topic)
    service.serve(server)
    service.wait()

Then, you can do

$ kill -USR2 $SERVICE_PID

and get a Guru Meditation Report in the file or terminal where stderr is logged for that given service.

class oslo_reports.guru_meditation_report.GuruMeditation(version_obj, sig_handler_tb=None, *args, **kwargs)

Bases: object

A Guru Meditation Report Mixin/Base Class

This class is a base class for Guru Meditation Reports. It provides facilities for registering sections and setting up functionality to auto-run the report on a certain signal or use file modification events.

This class should always be used in conjunction with a Report class via multiple inheritance. It should always come first in the class list to ensure the MRO is correct.

classmethod handle_signal(version, service_name, log_dir, frame)

The Signal Handler

This method (indirectly) handles receiving a registered signal and dumping the Guru Meditation Report to stderr or a file in a given dir. If service name and log dir are not None, the report will be dumped to a file named $service_name_gurumeditation_$current_time in the log_dir directory. This method is designed to be curried into a proper signal handler by currying out the version parameter.

Parameters:

  • version – the version object for the current product

  • service_name – this program name used to construct logfile name

  • logdir – path to a log directory where to create a file

  • frame – the frame object provided to the signal handler

classmethod register_section(section_title, generator)

Register a New Section

This method registers a persistent section for the current class.

Parameters:

  • section_title (str) – the title of the section

  • generator – the generator for the section

run()
classmethod setup_autorun(version, service_name=None, log_dir=None, signum=None, conf=None, setup_signal=True)

Set Up Auto-Run

This method sets up the Guru Meditation Report to automatically get dumped to stderr or a file in a given dir when the given signal is received. It can also use file modification events instead of signals.

Parameters:

  • version – the version object for the current product

  • service_name – this program name used to construct logfile name

  • logdir – path to a log directory where to create a file

  • signum – the signal to associate with running the report

  • conf – Configuration object, managed by the caller.

  • setup_signal – Set up a signal handler

timestamp_fmt = '%Y%m%d%H%M%S'
class oslo_reports.guru_meditation_report.TextGuruMeditation(version_obj, traceback=None)

Bases: GuruMeditation, TextReport

A Text Guru Meditation Report

This report is the basic human-readable Guru Meditation Report

It contains the following sections by default (in addition to any registered persistent sections):

  • Package Information

  • Threads List

  • Green Threads List

  • Process List

  • Configuration Options

Parameters:

  • version_obj – the version object for the current product

  • traceback – an (optional) frame object providing the actual traceback for the current thread

oslo_reports.opts module

oslo_reports.opts.list_opts()

Return a list of oslo.config options available in the library.

The returned list includes all oslo.config options which may be registered at runtime by the library. Each element of the list is a tuple. The first element is the name of the group under which the list of elements in the second element will be registered. A group name of None corresponds to the [DEFAULT] group in config files. This function is also discoverable via the ‘oslo_messaging’ entry point under the ‘oslo.config.opts’ namespace. The purpose of this is to allow tools like the Oslo sample config file generator to discover the options exposed to users by this library.

Returns:

a list of (group_name, opts) tuples

oslo_reports.opts.set_defaults(conf)

Set defaults for configuration variables.

Overrides default options values.

Parameters:

conf (oslo.config.cfg.ConfigOpts) – Configuration object, managed by the caller.

oslo_reports.report module

Provides Report classes

This module defines various classes representing reports and report sections. All reports take the form of a report class containing various report sections.

class oslo_reports.report.BasicReport

Bases: object

A Basic Report

A Basic Report consists of a collection of ReportSection objects, each of which contains a top-level model and generator. It collects these sections into a cohesive report which may then be serialized by calling run().

add_section(view, generator, index=None)

Add a section to the report

This method adds a section with the given view and generator to the report. An index may be specified to insert the section at a given location in the list; If no index is specified, the section is appended to the list. The view is called on the model which results from the generator when the report is run. A generator is simply a method or callable object which takes no arguments and returns a oslo_reports.models.base.ReportModel or similar object.

Parameters:

  • view – the top-level view for the section

  • generator – the method or class which generates the model

  • index (int or None) – the index at which to insert the section (or None to append it)

run()

Run the report

This method runs the report, having each section generate its data and serialize itself before joining the sections together. The BasicReport accomplishes the joining by joining the serialized sections together with newlines.

Return type:

str

Returns:

the serialized report

class oslo_reports.report.ReportOfType(tp)

Bases: BasicReport

A Report of a Certain Type

A ReportOfType has a predefined type associated with it. This type is automatically propagated down to the each of the sections upon serialization by wrapping the generator for each section.

See also

Class oslo_reports.models.with_default_view.ModelWithDefaultView # noqa

(the entire class)

Class oslo_reports.models.base.ReportModel

oslo_reports.models.base.ReportModel.set_current_view_type() # noqa

Parameters:

tp (str) – the type of the report

add_section(view, generator, index=None)

Add a section to the report

This method adds a section with the given view and generator to the report. An index may be specified to insert the section at a given location in the list; If no index is specified, the section is appended to the list. The view is called on the model which results from the generator when the report is run. A generator is simply a method or callable object which takes no arguments and returns a oslo_reports.models.base.ReportModel or similar object.

Parameters:

  • view – the top-level view for the section

  • generator – the method or class which generates the model

  • index (int or None) – the index at which to insert the section (or None to append it)

class oslo_reports.report.ReportSection(view, generator)

Bases: object

A Report Section

A report section contains a generator and a top-level view. When something attempts to serialize the section by calling str() or unicode() on it, the section runs the generator and calls the view on the resulting model.

See also

Class BasicReport

BasicReport.add_section()

Parameters:

  • view – the top-level view for this section

  • generator – the generator for this section (any callable object which takes no parameters and returns a data model)

class oslo_reports.report.TextReport(name)

Bases: ReportOfType

A Human-Readable Text Report

This class defines a report that is designed to be read by a human being. It has nice section headers, and a formatted title.

Parameters:

name (str) – the title of the report

add_section(heading, generator, index=None)

Add a section to the report

This method adds a section with the given title, and generator to the report. An index may be specified to insert the section at a given location in the list; If no index is specified, the section is appended to the list. The view is called on the model which results from the generator when the report is run. A generator is simply a method or callable object which takes no arguments and returns a oslo_reports.models.base.ReportModel or similar object.

The model is told to serialize as text (if possible) at serialization time by wrapping the generator. The view model’s attached view (if any) is wrapped in a oslo_reports.views.text.header.TitledView

Parameters:

  • heading (str) – the title for the section

  • generator – the method or class which generates the model

  • index (int or None) – the index at which to insert the section (or None to append)

Module contents

Provides a way to generate serializable reports

This package/module provides mechanisms for defining reports which may then be serialized into various data types. Each report ( oslo_reports.report.BasicReport ) is composed of one or more report sections ( oslo_reports.report.BasicSection ), which contain generators which generate data models ( oslo_reports.models.base.ReportModels ), which are then serialized by views.