Repository Public License
1<!--2ORIX Monitor3File: docs/architecture/reporting.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Reporting910Sources:1112- `Packages/ORIXMonitorCore/Sources/ORIXMonitorCore/Reporting/ReportGenerator.swift` — value formatting, report model, Markdown / CSV / JSON renderers, comparison.13- `App/Sources/Reporting/PDFReportRenderer.swift` — PDF renderer.14- `App/Sources/Features/ReportsView.swift` — builder UI, export, comparison UI.1516A 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.1718## Flow1920```mermaid21flowchart LR22 ST["TimeSeriesStore.series per metric"] --> IN["ReportInputs"]23 EVT["TimeSeriesStore.events"] --> IN24 LIVE["Current snapshot: volumes, interfaces, processes, power"] --> IN25 FND["MonitorModel.findings in the period"] --> IN26 SYS["SystemInfo"] --> IN27 IN --> B["ReportGenerator.build"]28 B --> R["Report (Codable)"]29 R --> MD["markdown()"]30 R --> CSV["csv()"]31 R --> JS["json()"]32 R --> PDF["PDFReportRenderer.render()"]33 JS --> CMP["compare(a, b)"]34```3536## Report kinds3738`ReportKind` and the metrics each one queries (`ReportKind.metrics`):3940| Kind | Title | Metrics |41|---|---|---|42| `system` | System Overview Report | `cpuTotal`, `memUsed`, `memPressure`, `swapUsed`, `diskFree`, `diskRead`, `diskWrite`, `netDown`, `netUp`, `thermalState`, `gpuUtilization`, `batteryCharge` |43| `cpu` | CPU Analysis Report | `cpuTotal`, `cpuUser`, `cpuSystem`, `loadAverage1` |44| `memory` | Memory Analysis Report | `memUsed`, `memApp`, `memWired`, `memCompressed`, `memCached`, `memFree`, `memPressure`, `swapUsed`, `pageIns`, `pageOuts` |45| `storage` | Storage Analysis Report | `diskFree`, `diskRead`, `diskWrite` |46| `network` | Network Analysis Report | `netDown`, `netUp` |47| `processes` | Process Activity Report | `processCount`, `cpuTotal` |48| `incident` | Performance Incident Report | `cpuTotal`, `memUsed`, `memPressure`, `swapUsed`, `diskRead`, `diskWrite`, `netDown`, `netUp`, `thermalState` |4950## Period5152| Kind | Period |53|---|---|54| All except incident | The last 1 hour, 6 hours, 24 hours, 7 days, 30 days or 1 year (`HistoryRange`) |55| Incident | 30 minutes before to 30 minutes after a moment chosen with a date picker (the end is capped at now) |5657`ReportsView.build()` queries each metric with `maxPoints: 360` and lets the store choose the tier (see [storage](storage.md)). 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.5859## Report model6061`Report` (Codable, Sendable):6263| Field | Content |64|---|---|65| `kind`, `title` | Kind and localised title |66| `generated`, `from`, `to` | Dates |67| `samplingInterval` | The configured foreground interval at build time |68| `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` |69| `series` | `[ReportSeriesSummary]` |70| `tables` | `[ReportTable]` (title, headers, rows) |71| `findings` | `[Finding]` |72| `limitations` | Localised sentences |73| `appVersion` | `CFBundleShortVersionString` |7475`ReportSeriesSummary` joins the stored `Series` with the metric catalogue: `metric`, `name`, `unit`, `quality`, `source`, `method`, `tier`, `step`, `sampleCount`, `minimum`, `average`, `maximum`, `gaps`, `points`.7677Tables added by `ReportGenerator.build`:7879| Table | Included for | Content |80|---|---|---|81| Volumes | `system`, `storage` | Name, format, capacity, available, used % |82| Network interfaces | `system`, `network` | Active interfaces only: name, kind, status, received, sent (cumulative) |83| 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 |84| Battery | `system`, when the Mac has a battery | Charge, power source, and — labelled "(best effort)" — cycle count and capacity versus design |85| Events | any kind, when events were supplied | Up to 100: time, kind, code, payload as `key=value` pairs |8687Volumes, 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.8889### Limitations section9091Always present:92931. Values come from the interfaces listed for each metric. Nothing is simulated or interpolated across gaps.942. History exists only for periods when ORIX Monitor was running; gaps are listed per metric.953. CPU percentages for the whole Mac use 100 % = all cores busy. Per-process figures use 100 % = one core.964. Metrics marked "best effort" are read from system properties Apple does not document and may be absent.975. Temperatures, fan speeds, SSD health and per-process network traffic are not available through supported system interfaces.9899When every series is empty, "No stored samples exist for the selected period." is inserted first.100101## Privacy defaults102103- The host name is included only when "Include this Mac's host name" is on (`AppSettings.includeHostInReports`, off by default). The test `markdownContainsUnitsMethodsGapsAndLimitations` asserts its absence by default.104- 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.105- Process names, volume names and event payloads (which can contain a bookmark note or a process name) **are** included.106107## Formatting108109`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`.110111Level 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.112113Localisation: `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.114115## Export formats116117`ReportFormat`: `pdf`, `markdown`, `csv`, `json`. Files are saved through an `NSSavePanel` with the default name `ORIX-Monitor-<kind>-<yyyy-mm-dd>.<ext>`.118119### Markdown — `ReportGenerator.markdown(_:formatter:localize:)`120121Sections, 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.122123### CSV — `ReportGenerator.csv(_:)`124125Long format, one row per bucket and metric:126127```128metric,name,unit,quality,tier,bucket_seconds,timestamp_iso8601,timestamp_unix,min,avg,max,samples129```130131Numbers 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.132133### JSON — `ReportGenerator.json(_:)`134135The whole `Report` value encoded with `JSONEncoder` (`prettyPrinted`, `sortedKeys`, ISO 8601 dates). It round-trips through `JSONDecoder` (`jsonRoundTrips`) and is the input of report comparison.136137### PDF — `PDFReportRenderer.render()`138139A small top-down layout engine over a Core Graphics PDF context and Core Text:140141- US Letter pages (612 × 792 pt), 48 pt margins, automatic page breaks, a footer with the report title and page number.142- Title block, **System** and **Metrics** tables.143- 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.144- The report's tables, **Findings** (title, severity and the same explanatory sentence as the Insights page), **Collection methods**, **Data gaps**, **Limitations**.145- PDF metadata: title and creator ("ORIX Monitor <version>").146- 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.147148## Report comparison149150`ReportGenerator.compare(_ a:_ b:formatter:localize:)` returns a `ReportTable` titled "Comparison" with one row per metric present in both reports:151152| Column | Content |153|---|---|154| Metric | Name from report A |155| Average A, Average B | Formatted in the metric's unit |156| Change | `(B − A) / |A| × 100`, one decimal; "—" when either average is missing or A is zero |157| Peak A, Peak B | Maxima |158159In 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.160161## Other exports162163The 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`).164165## Limitations166167- **No scheduled or automatic reports**, no report archive inside the app, no sharing: every export is a manual save.168- **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.169- **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.170- **PDF is single column, US Letter only**; there is no A4 option and no table of contents.171- **Live tables are a single moment.** The top-process table does not describe the busiest processes over the period.172- **The comparison table prints level metrics as numbers** (it formats by unit); the report tables themselves print names.173- **`samplingInterval` is the configured foreground interval**, not the effective interval of each stored sample; the resolution actually used is given per metric (`step`, `tier`).174