Graduating 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 “”, but pluralizing the name seems more natural.


openstack/common/report/ openstack/common/report/ openstack/common/report/ openstack/common/report/ openstack/common/report/views/ openstack/common/report/views/text/ openstack/common/report/views/text/ openstack/common/report/views/text/ openstack/common/report/views/text/ openstack/common/report/views/xml/ openstack/common/report/views/xml/ openstack/common/report/views/ openstack/common/report/views/json/ openstack/common/report/views/json/ openstack/common/report/generators/ openstack/common/report/generators/ openstack/common/report/generators/ openstack/common/report/generators/ openstack/common/report/models/ openstack/common/report/models/ openstack/common/report/models/ openstack/common/report/models/ openstack/common/report/models/ openstack/common/report/models/

tests/unit/reports/ tests/unit/reports/ tests/unit/reports/ tests/unit/reports/

Early Adopters


Public API

The reports module contains several public submodules:


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

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


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


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


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:


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.


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.



Primary assignee:


Other contributors:


Primary Maintainer

Primary Maintainer:


Other Contributors:


Security Contact

Security Contact:



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



  • oslo.utils

  • oslo.serialization




This work is licensed under a Creative Commons Attribution 3.0 Unported License.