Reporting
Sources:
Packages/ORIXMonitorCore/Sources/ORIXMonitorCore/Reporting/ReportGenerator.swift— value formatting, report model, Markdown / CSV / JSON renderers, comparison.App/Sources/Reporting/PDFReportRenderer.swift— PDF renderer.App/Sources/Features/ReportsView.swift— builder UI, export, comparison UI.
A report is a snapshot of stored measurements over a period, with the provenance of every metric, the gaps in the data and a fixed list of limitations. Nothing in a report is simulated or interpolated.
Flow
flowchart LR
ST["TimeSeriesStore.series per metric"] --> IN["ReportInputs"]
EVT["TimeSeriesStore.events"] --> IN
LIVE["Current snapshot: volumes, interfaces, processes, power"] --> IN
FND["MonitorModel.findings in the period"] --> IN
SYS["SystemInfo"] --> IN
IN --> B["ReportGenerator.build"]
B --> R["Report (Codable)"]
R --> MD["markdown()"]
R --> CSV["csv()"]
R --> JS["json()"]
R --> PDF["PDFReportRenderer.render()"]
JS --> CMP["compare(a, b)"]
Report kinds
ReportKind and the metrics each one queries (ReportKind.metrics):
| Kind | Title | Metrics |
|---|---|---|
system |
System Overview Report | cpuTotal, memUsed, memPressure, swapUsed, diskFree, diskRead, diskWrite, netDown, netUp, thermalState, gpuUtilization, batteryCharge |
cpu |
CPU Analysis Report | cpuTotal, cpuUser, cpuSystem, loadAverage1 |
memory |
Memory Analysis Report | memUsed, memApp, memWired, memCompressed, memCached, memFree, memPressure, swapUsed, pageIns, pageOuts |
storage |
Storage Analysis Report | diskFree, diskRead, diskWrite |
network |
Network Analysis Report | netDown, netUp |
processes |
Process Activity Report | processCount, cpuTotal |
incident |
Performance Incident Report | cpuTotal, memUsed, memPressure, swapUsed, diskRead, diskWrite, netDown, netUp, thermalState |
Period
| Kind | Period |
|---|---|
| All except incident | The last 1 hour, 6 hours, 24 hours, 7 days, 30 days or 1 year (HistoryRange) |
| Incident | 30 minutes before to 30 minutes after a moment chosen with a date picker (the end is capped at now) |
ReportsView.build() queries each metric with maxPoints: 360 and lets the store choose the tier (see storage). Events (kinds alert, system, bookmark, process, limit 100) are loaded only for the incident and system kinds. Findings are those in MonitorModel.findings whose interval overlaps the period. A Refresh button rebuilds the report with the latest stored samples.
Report model
Report (Codable, Sendable):
| Field | Content |
|---|---|
kind, title |
Kind and localised title |
generated, from, to |
Dates |
samplingInterval |
The configured foreground interval at build time |
system |
Rows of label/value: model, chip, macOS version and build, memory, CPU cores (with the kernel's group names), uptime; host name first only if includeHostName |
series |
[ReportSeriesSummary] |
tables |
[ReportTable] (title, headers, rows) |
findings |
[Finding] |
limitations |
Localised sentences |
appVersion |
CFBundleShortVersionString |
ReportSeriesSummary joins the stored Series with the metric catalogue: metric, name, unit, quality, source, method, tier, step, sampleCount, minimum, average, maximum, gaps, points.
Tables added by ReportGenerator.build:
| Table | Included for | Content |
|---|---|---|
| Volumes | system, storage |
Name, format, capacity, available, used % |
| Network interfaces | system, network |
Active interfaces only: name, kind, status, received, sent (cumulative) |
| Top processes by CPU / by memory | system, processes, cpu, memory, incident |
Processes with statistics, top 10 (25 for processes), sorted by memory for the memory kind and by CPU otherwise: name, PID, CPU, memory, CPU time |
| Battery | system, when the Mac has a battery |
Charge, power source, and — labelled "(best effort)" — cycle count and capacity versus design |
| Events | any kind, when events were supplied | Up to 100: time, kind, code, payload as key=value pairs |
Volumes, interfaces, processes and battery describe the moment the report is built (they come from the current snapshot), not the whole period. Only the series, events and findings are historical.
Limitations section
Always present:
- Values come from the interfaces listed for each metric. Nothing is simulated or interpolated across gaps.
- History exists only for periods when ORIX Monitor was running; gaps are listed per metric.
- CPU percentages for the whole Mac use 100 % = all cores busy. Per-process figures use 100 % = one core.
- Metrics marked "best effort" are read from system properties Apple does not document and may be absent.
- Temperatures, fan speeds, SSD health and per-process network traffic are not available through supported system interfaces.
When every series is empty, "No stored samples exist for the selected period." is inserted first.
Privacy defaults
- The host name is included only when "Include this Mac's host name" is on (
AppSettings.includeHostInReports, off by default). The testmarkdownContainsUnitsMethodsGapsAndLimitationsasserts its absence by default. - The report model has no field for the serial number, IP addresses or user names. Interface rows carry names and byte totals, not addresses; process rows carry name and PID, not the owning user or the executable path.
- Process names, volume names and event payloads (which can contain a bookmark note or a process name) are included.
Formatting
ValueFormatter(locale:) is shared by the interface and the reports: bytes (file or memory style), rate (bytes per second), percent, number, duration, clock, temperature, date, and value(_:unit:) which dispatches on MetricUnit.
Level metrics are shown by name, never as a bare number: ReportGenerator.display(_:metric:unit:formatter:localize:) maps memory pressure to Normal / Warning / Critical and thermal state to Nominal / Fair / Serious / Critical, and prints available space in file-size units. The Markdown renderer uses it; the preview and the PDF use the app's equivalent, AlertText.formatted. The test levelMetricsAreNamedNotNumbered covers the mapping.
Localisation: ReportGenerator.build, markdown and display take a Localizer closure ((String) -> String, identity by default). The app passes L, its string-catalogue lookup, so headings, metric names and limitation sentences are translated while the core stays independent of the app bundle.
Export formats
ReportFormat: pdf, markdown, csv, json. Files are saved through an NSSavePanel with the default name ORIX-Monitor-<kind>-<yyyy-mm-dd>.<ext>.
Markdown — ReportGenerator.markdown(_:formatter:localize:)
Sections, in order: title; version and generation date; period and sampling interval; System; Metrics (minimum, average, maximum, samples, resolution, quality); one section per table; Findings (if any); Collection methods (unit, source API, method per metric); Data gaps (count, total missing, longest per metric, or "No gap in the selected period."); Limitations. Pipe characters inside cells are escaped.
CSV — ReportGenerator.csv(_:)
Long format, one row per bucket and metric:
metric,name,unit,quality,tier,bucket_seconds,timestamp_iso8601,timestamp_unix,min,avg,max,samplesNumbers use a dot as decimal separator and no grouping, regardless of locale, so any tool can parse them. metric is the stable key (cpu.total, …). Names containing a comma, quote or newline are quoted with doubled quotes (ReportGenerator.field). The CSV holds only the series; tables, findings and limitations are not in it.
JSON — ReportGenerator.json(_:)
The whole Report value encoded with JSONEncoder (prettyPrinted, sortedKeys, ISO 8601 dates). It round-trips through JSONDecoder (jsonRoundTrips) and is the input of report comparison.
PDF — PDFReportRenderer.render()
A small top-down layout engine over a Core Graphics PDF context and Core Text:
- US Letter pages (612 × 792 pt), 48 pt margins, automatic page breaks, a footer with the report title and page number.
- Title block, System and Metrics tables.
- One chart per series with more than one point: 96 pt high, the min–max band filled and the average line stroked in the accent colour, gaps shaded, the line broken wherever consecutive points are more than 2.5 steps apart. The y axis runs from
min(0, minimum)to the maximum; the x axis spans the report period. - The report's tables, Findings (title, severity and the same explanatory sentence as the Insights page), Collection methods, Data gaps, Limitations.
- PDF metadata: title and creator ("ORIX Monitor ").
- Colours are fixed light-mode values (ink
#0E1222, muted#596078, rule#DDE0EA, accent#0891B2) so the document prints the same whatever the app's appearance.
Report comparison
ReportGenerator.compare(_ a:_ b:formatter:localize:) returns a ReportTable titled "Comparison" with one row per metric present in both reports:
| Column | Content |
|---|---|
| Metric | Name from report A |
| Average A, Average B | Formatted in the metric's unit |
| Change | `(B − A) / |
| Peak A, Peak B | Maxima |
In the UI ("Compare Two Saved Reports…") the user selects exactly two JSON files exported earlier; they are decoded, ordered by their from date (earlier = A) and compared. Errors are reported inline: not exactly two files, a file that is not an ORIX Monitor report, or two reports sharing no metric.
Other exports
The History page exports independently of the report model: a chart as PNG (ImageRenderer, 1100 × 420 pt at 2×, with the metric name, period and source) and one series as CSV (metric,unit,tier,bucket_seconds,timestamp_iso8601,min,avg,max,samples).
Limitations
- No scheduled or automatic reports, no report archive inside the app, no sharing: every export is a manual save.
- The on-screen preview is not the PDF. It shows the metrics table, up to 40 rows of each table, finding titles and limitations, without charts.
- Comparison works on averages and peaks only, and does not check that the two reports are of the same kind or cover periods of equal length.
- PDF is single column, US Letter only; there is no A4 option and no table of contents.
- Live tables are a single moment. The top-process table does not describe the busiest processes over the period.
- The comparison table prints level metrics as numbers (it formats by unit); the report tables themselves print names.
samplingIntervalis the configured foreground interval, not the effective interval of each stored sample; the resolution actually used is given per metric (step,tier).