MiqReport Engine & Custom Reports

Relevant source files

The following files were used as context for generating this wiki page:

• app/models/miq_report/generator.rb
• app/models/miq_report_result.rb
• lib/manageiq/reporting/formatter/text.rb
• lib/manageiq/reporting/formatter/html.rb
• spec/models/miq_report_spec.rb
• spec/models/miq_report_result_spec.rb
• product/charts/miq_reports/vim_perf_util_4_ts.yaml

The MiqReport Engine is the core component responsible for defining, generating, and persisting data reports within the ManageIQ platform. It supports a wide variety of data sources, including standard database models, performance metrics (C&U), and custom chargeback data. The system allows for both synchronous and asynchronous generation, resulting in MiqReportResult objects that store the final output in formats such as HTML, CSV, TXT, or PDF.

Sources: app/models/miq_report/generator.rb, app/models/miq_report_result.rb, spec/models/miq_report_spec.rb

Core Architecture and Data Model

The reporting system relies on a relationship between the report definition (MiqReport) and the generated output (MiqReportResult). Reports are defined with specific columns, includes (associations), and conditions using the MiqExpression syntax.

Key Data Structures

Component	Description
MiqReport	The definition object containing SQL options, column orders, headers, and formatting rules.
MiqReportResult	The instance of a generated report, linking the output to a specific user, task, and group.
BinaryBlob	Used by MiqReportResult to store large report data (like YAML/hash tables) in the database.
Ruport::Data::Table	The internal representation of report data during the generation process.

Sources: app/models/miq_report_result.rb:1-15, app/models/miq_report/generator.rb:360-380, product/charts/miq_reports/vim_perf_util_4_ts.yaml

Relationships Diagram

The following diagram illustrates the relationship between reports, results, and the background tasks that generate them.

Report Generation Flow

Report generation can be triggered synchronously via generate_table or asynchronously via the MiqQueue.

Generation Logic

The engine determines the retrieval method based on the report type:

1. Basic Results: Uses Rbac.search to fetch standard database records based on db_class.
2. Performance Results: Specialized logic for MetricRollup and performance intervals (hourly/daily).
3. Custom Methods: Some reports define a custom_results_method for specialized data gathering (e.g., Chargeback).

Asynchronous Execution

Asynchronous requests create an MiqTask and submit an _async_generate_table message to the reporting role in the MiqQueue. This ensures that large reports do not block the web interface.

Sources: app/models/miq_report/generator.rb:104-123, spec/models/miq_report_result_spec.rb:15-28

Formatting and Output

The engine utilizes various formatters to transform raw data into user-readable formats. Formatting includes currency, number delimiters, and human-readable bytes.

Formatter Types

• HTML Formatter: Generates standard bootstrap-styled tables for the UI.
• Text Formatter: Creates ASCII-style tables with column alignment and headers.
• PDF Formatter: Uses PdfGenerator to convert HTML strings into PDF documents with custom headers and page numbering.

Sources: lib/manageiq/reporting/formatter/html.rb:29-50, lib/manageiq/reporting/formatter/text.rb:7-40, app/models/miq_report_result.rb:151-170

Formatting Functions

The reporting engine provides several helper methods for data conversion:

• format_currency_with_delimiter: Adds currency units ($, €, etc.) and formatting.
• format_bytes_to_human_size: Converts integers into "KB", "MB", "GB", etc.
• format_relative_date: Converts timestamps into phrases like "about 1 year ago".

Sources: spec/models/miq_report/formatting_spec.rb:4-60

Custom Attributes and Virtual Columns

The engine supports reporting on dynamic data through "Virtual Custom Attributes." This allows users to include tags and custom attributes (like those from Kubernetes labels or OpenStack metadata) as if they were standard database columns.

Summary

The MiqReport Engine is a robust reporting framework that abstracts the complexity of data retrieval and formatting. By utilizing background tasks and a flexible formatting layer, it enables the generation of highly customized reports across the entire ManageIQ object model, supporting everything from simple inventory lists to complex resource utilization trends.

Sources: app/models/miq_report/generator.rb, app/models/miq_report_result.rb