---
id: oslo-reports
version: "3.9.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# oslo.reports — oslo.reports library

License: permissive · Maintenance: active · Downloads: 165.2K/mo

## What it is and what it does

oslo.reports is a framework for generating structured diagnostic reports from running OpenStack services. It addresses the problem that logs alone don't capture the live state of a system—what threads are active, which config parameters are in effect, or what exceptions are currently being handled. The package provides a "guru meditation report" mechanism that collects this state into models (stack traces, thread info, exceptions, config, package versions) and serializes them to JSON, XML, or plain text via Jinja templates.

The framework is built on three layers: Models that define structured data for system state, Generators that populate those models with current runtime information, and Views that serialize the models to output formats. OpenStack projects can register custom generators to add project-specific diagnostic data. It depends on oslo.serialization, oslo.config, oslo.i18n, oslo.utils, Jinja2, psutil, and pbr—all mature OpenStack ecosystem libraries.

Use it for:

- Generate diagnostic snapshots when an OpenStack service encounters an error or hangs, capturing thread stacks and active configuration.
- Collect runtime state reports from production deployments to aid in triaging and debugging complex distributed system issues.
- Export system state in machine-readable formats (JSON, XML) for automated analysis or archival in incident response workflows.
- Extend with custom generators to include application-specific metrics or state in the diagnostic report.
- Inspect thread behavior and configuration state without stopping or restarting the running service.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

oslo.reports generates structured debug reports from running OpenStack services, capturing thread state, configuration, stack traces, and package information in JSON, XML, or templated text format.

Yes, if you are developing or operating an OpenStack service and need structured diagnostic reporting. The package is actively maintained, has no known vulnerabilities, and integrates cleanly with the oslo ecosystem. Not recommended for non-OpenStack projects unless you need a general-purpose runtime state capture framework and are willing to work with its OpenStack-centric design.

## Install

pip install oslo-reports
uv add oslo-reports
poetry add oslo-reports

## Installing oslo.reports

Before you install: Low install friction with a pure-Python wheel. Active maintenance as of 35 days ago. Depends on 7 runtime packages including oslo.serialization, oslo.config, and Jinja2—all standard OpenStack libraries with established track records.

License in practice: Apache-2.0 permissive license allows use in commercial and proprietary projects with minimal restrictions; attribution required but no copyleft obligations.

Quickstart:

pip install oslo.reports

from oslo_reports.guru_meditation_report import GuruMeditationReport
report = GuruMeditationReport()
print(report.format_report())

Requires Python 3.11 or later; designed for OpenStack deployments and most useful when integrated into an OpenStack service.

Verify before relying:

- Whether the package works standalone or requires an OpenStack service context to be useful.
- Performance characteristics when generating reports from long-running processes with many threads.
- Customization API surface for adding project-specific generators and models beyond the documented standard set.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 165.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

openstack debug report generation, guru meditation report, runtime state capture, thread and config inspection, openstack diagnostic reporting, system state serialization, error report framework, openstack, diagnostics, runtime-introspection

[View on SkillFed](https://skillfed.io/packages/oslo-reports) · [View on PyPI](https://pypi.org/project/oslo-reports/)