{"id":9161,"library":"oslo-reports","title":"Oslo Reports Library","description":"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.","status":"active","version":"3.7.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/oslo.reports","tags":["OpenStack","reporting","diagnostics","error reporting","system information","utilities"],"install":[{"cmd":"pip install oslo.reports","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for standardized configuration across OpenStack projects, which oslo.reports may leverage for gathering configuration data. Not a strict runtime dependency for basic report generation.","package":"oslo.config","optional":true},{"reason":"Required for using predefined views that utilize the Jinja templating system for report serialization (e.g., text or HTML output). Not required for JSON or XML views.","package":"jinja2","optional":true}],"imports":[{"note":"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.","wrong":"from oslo.reports.guru_meditation_report import GuruMeditationReport","symbol":"GuruMeditationReport","correct":"from oslo_reports.guru_meditation_report import GuruMeditationReport"},{"note":"Base class for custom report models.","symbol":"ReportModel","correct":"from oslo_reports.models.base import ReportModel"},{"note":"A model class that includes default views for various serialization formats (text, JSON, XML).","symbol":"ModelWithDefaultViews","correct":"from oslo_reports.models.with_default_views import ModelWithDefaultViews"}],"quickstart":{"code":"from oslo_reports.guru_meditation_report import GuruMeditationReport\n\n# Create a Guru Meditation Report instance.\n# By default, it gathers extensive system information.\n# Additional generators can be registered for custom data.\ngmr = GuruMeditationReport()\n\n# Generate the report as a plain text string.\n# Other rendering methods (e.g., to JSON, XML) may be available\n# depending on installed optional dependencies and specific views.\nreport_text = gmr.render_report(output_format='text')\n\nprint(\"--- Guru Meditation Report ---\")\nprint(report_text)\nprint(\"----------------------------\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or higher. Use `python --version` to check your current interpreter version.","message":"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.","severity":"breaking","affected_versions":"<3.10"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import oslo_reports` or `from oslo_reports...` and ensure the package is installed via `pip install 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.","error":"ModuleNotFoundError: No module named 'oslo.reports'"},{"fix":"Install the Jinja2 templating engine: `pip install jinja2`. If using a specific `oslo.reports` view that relies on Jinja, ensure it's available.","cause":"A report view configured to use Jinja2 templates cannot find the necessary templates, likely because the `jinja2` package is not installed.","error":"jinja2.exceptions.TemplateNotFound: ..."},{"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.","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.","error":"AttributeError: 'GuruMeditationReport' object has no attribute 'render_html_report'"}]}