SPB Git

Repository Public License

reporting.md 11.0 KB

# 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:

  1. Values come from the interfaces listed for each metric. Nothing is simulated or interpolated across gaps.
  2. History exists only for periods when ORIX Monitor was running; gaps are listed per metric.
  3. CPU percentages for the whole Mac use 100 % = all cores busy. Per-process figures use 100 % = one core.
  4. Metrics marked "best effort" are read from system properties Apple does not document and may be absent.
  5. 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 test markdownContainsUnitsMethodsGapsAndLimitations asserts 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:

text
metric,name,unit,quality,tier,bucket_seconds,timestamp_iso8601,timestamp_unix,min,avg,max,samples

Numbers 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.
  • samplingInterval is the configured foreground interval, not the effective interval of each stored sample; the resolution actually used is given per metric (step, tier).
Files main
Menu

Theme