Oslo Reports Library

3.7.0 · active · verified Thu Apr 16

oslo.reports is an OpenStack library that provides a general-purpose framework for generating detailed error and system reports, often referred to as 'Guru Meditation Reports'. It helps administrators obtain an accurate view of the current live state of a system, including running threads, configuration parameters, and package versions. The current version is 3.7.0, and it follows the OpenStack project's regular release cadence.

Common errors

```
ModuleNotFoundError: No module named 'oslo.reports'
```
cause The Python import statement uses `oslo.reports` (with a dot) instead of `oslo_reports` (with an underscore), or the package is not installed.

fix Change your import statement to `import oslo_reports` or `from oslo_reports...` and ensure the package is installed via `pip install oslo.reports`.
```
jinja2.exceptions.TemplateNotFound: ...
```
cause A report view configured to use Jinja2 templates cannot find the necessary templates, likely because the `jinja2` package is not installed.

fix Install the Jinja2 templating engine: `pip install jinja2`. If using a specific `oslo.reports` view that relies on Jinja, ensure it's available.
```
AttributeError: 'GuruMeditationReport' object has no attribute 'render_html_report'
```
cause Attempting to use a specific report rendering method (e.g., for HTML) that is not supported by default or requires a particular optional dependency or custom view setup.

fix Check the documentation for available `render_report` formats. If a specific format is desired, ensure the necessary view classes and their dependencies (like Jinja2 for HTML/templated text) are installed and correctly configured with the `GuruMeditationReport` instance.

Warnings

breaking The library explicitly requires Python 3.10 or newer. Attempting to install or run oslo.reports on older Python versions will result in installation failures or runtime errors.
Fix: Upgrade your Python environment to version 3.10 or higher. Use `python --version` to check your current interpreter version.
gotcha Module import paths use underscores (`oslo_reports`) while the PyPI package name uses a dash (`oslo-reports`). A common mistake is to try `import oslo.reports`.
Fix: Always use `import oslo_reports` or `from oslo_reports.module import ...` in your Python code, even though you install it as `pip install oslo.reports`.
gotcha Generating reports with specific output formats (e.g., templated text via Jinja2) or incorporating configuration data requires installing optional dependencies like `jinja2` or having `oslo.config` properly set up.
Fix: If experiencing errors related to missing templates or configuration, ensure that relevant optional dependencies are installed (`pip install oslo.reports[jinja2]` if available, or `pip install jinja2 oslo.config` separately) and that `oslo.config` is initialized if configuration is expected.

Install

pip install oslo.reports Install latest version

Imports

GuruMeditationReport
wrong:
```
from oslo.reports.guru_meditation_report import GuruMeditationReport
```
correct:
```
from oslo_reports.guru_meditation_report import GuruMeditationReport
```
The PyPI package name uses a dash (`oslo-reports`), but the Python import path uses an underscore (`oslo_reports`). Using the dash in the import will result in a ModuleNotFoundError.

ReportModel

from oslo_reports.models.base import ReportModel

Base class for custom report models.

ModelWithDefaultViews
```
from oslo_reports.models.with_default_views import ModelWithDefaultViews
```
A model class that includes default views for various serialization formats (text, JSON, XML).

Quickstart

This quickstart demonstrates how to generate a basic Guru Meditation Report. The `GuruMeditationReport` class, when instantiated, automatically collects a wide range of system diagnostics. The `render_report()` method then serializes this data into a human-readable string. By default, it attempts to use a text output format.

from oslo_reports.guru_meditation_report import GuruMeditationReport

# Create a Guru Meditation Report instance.
# By default, it gathers extensive system information.
# Additional generators can be registered for custom data.
gmr = GuruMeditationReport()

# Generate the report as a plain text string.
# Other rendering methods (e.g., to JSON, XML) may be available
# depending on installed optional dependencies and specific views.
report_text = gmr.render_report(output_format='text')

print("--- Guru Meditation Report ---")
print(report_text)
print("----------------------------")

view raw JSON →