oslo-specs/specs/liberty/graduate-oslo-reports.rst

Graduating Reports

https://blueprints.launchpad.net/oslo-incubator/+spec/graduate-oslo-reports

The reports module currently provides a convenient way to assemble "Guru Meditation Reports" about the current state a of a given OpenStack process. The basic report includes thread (both normal and green) state and stack traces, as well as configuration and version information. The reports are customizable and may be extended with additional sections on a per-process or per-project basis. A mechanism is also included to set up the reports to dump to stdout (or a file) on SIGUSR1, and may be serialized as text (default), as well as XML and JSON.

Library Name

The library will be called "oslo.reports". The current name in the incubator is "openstack.common.report", but pluralizing the name seems more natural.

Contents

openstack/common/report/report.py openstack/common/report/utils.py openstack/common/report/guru_meditation_report.py openstack/common/report/__init__.py openstack/common/report/views/__init__.py openstack/common/report/views/text/__init__.py openstack/common/report/views/text/generic.py openstack/common/report/views/text/threading.py openstack/common/report/views/text/header.py openstack/common/report/views/xml/__init__.py openstack/common/report/views/xml/generic.py openstack/common/report/views/jinja_view.py openstack/common/report/views/json/__init__.py openstack/common/report/views/json/generic.py openstack/common/report/generators/conf.py openstack/common/report/generators/__init__.py openstack/common/report/generators/version.py openstack/common/report/generators/threading.py openstack/common/report/models/base.py openstack/common/report/models/conf.py openstack/common/report/models/__init__.py openstack/common/report/models/version.py openstack/common/report/models/with_default_views.py openstack/common/report/models/threading.py

tests/unit/reports/test_base_report.py tests/unit/reports/test_guru_meditation_report.py tests/unit/reports/test_openstack_generators.py tests/unit/reports/test_views.py

Early Adopters

None

Public API

The reports module contains several public submodules:

reports.guru_meditation_report

Contains the code revolving around setting up the signal handler and registering persistent custom sections

reports.report

Contains the basic classes for the reports themselves, including a class for the whole report, a class for each section, and a subclass specifically for reports serialized as text

reports.generators

Contains the submodules containing generator code: conf, threading, version (not that there is no base module here since generators are just callables)

reports.models

Contains the submodules containing the base model classes (base and with_default_views) as well as the implementation model classes (threading, version, and conf)

report.views

Contains the submodule containing the basic Jinja-based view (jinja_view), as well as the JSON, XML, and text views (json, xml, and text, respectively). Note that each of the serialization-formatting submodules contains a generic submodule containing generic classes, and the text submodule additionally contains the header submodule (as well as the threading submodule, which may be made private).

The following submodules do not necessarily need to be public:

reports.utils

Contains a utility class for attaching attributes to strings, as well as a function for finding all objects of a particular class using the garbage collector functionality. Neither of these need to be exposed as public, and the object-finding function can be moved into the file of the generator which uses it (StringWithAttrs is used by both reports.views.xml.generic and reports.views.json.generic), so it needs to stay in its own file.

reports.views.text.threading

This contains several views specific to certain models (which already have them set as the default text view), so it does not need to be public.

Implementation

Assignee(s)

Primary assignee:

sross-7

Other contributors:

None

Primary Maintainer

Primary Maintainer:

sross-7

Other Contributors:

None

Security Contact

Security Contact:

sross-7

Milestones

Target Milestone for completion: Uknown

Work Items

The graduation checklist should be completed.

Additionally, there are a few places where reports currently uses str and should be using six.text_type instead. These should be fixed before graduation is complete.

Adoption Notes

None

Dependencies

• oslo.utils
• oslo.serialization

References

None

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode