SPB Git

Repository Public License

disk.md 9.2 KB 136 lines markdown

1<!--2ORIX Monitor3File: docs/metrics/disk.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Disk metrics910Sources: `Collectors/DiskCollector.swift` (`DiskCollector`, `DiskMath`, `VolumeInfo`, `PhysicalDisk`, `DiskCounters`, `DiskActivitySample`), `Metrics/Metric.swift`, `App/Sources/Features/SystemViews.swift` (`DiskView`).1112## Logical volumes versus physical disks1314The Disk page has two separate tables because macOS storage has two separate layers, and mixing them produces wrong totals.1516| | Logical volume (`VolumeInfo`) | Physical block device (`PhysicalDisk`) |17|---|---|---|18| What it is | A mounted file system: "Macintosh HD", "Data", an external drive's partition, a network share, a mounted disk image | A device the kernel does block I/O on: the internal SSD, an external drive, the virtual device behind a disk image |19| Identified by | Mount point (`/`, `/Volumes/…`) and BSD name such as `disk3s1` | BSD name of the whole device such as `disk0` |20| What it has | **Capacity**: total, available, free | **Activity**: bytes and operations read and written |21| Source | `FileManager` / `URLResourceValues`, DiskArbitration | IOKit `IOBlockStorageDriver` statistics |22| Tier | Slow (30 s by default, and on mount/unmount) | Fast (2 s by default) |2324Two consequences the interface states explicitly:25261. **Volume capacities must not be added together.** With APFS, several volumes share one container and one pool of free space. Each of them reports the container's size and the same available space. `VolumeInfo.containerBSDName` (shown as `disk3s1 ⊂ disk3`) makes the sharing visible. ORIX Monitor never sums capacities.272. **Throughput is counted on physical devices, not on volumes.** There is no per-volume I/O rate. Disk images appear as block devices, but their I/O is already counted on the device that stores the image file, so they are listed and **excluded from the totals**.2829## Stored metrics3031| Key (`MetricID`) | Name | Unit | Quality | Source API | Stored value | Refresh |32|---|---|---|---|---|---|---|33| `disk.read` (`diskRead`) | Disk read | bytes per second | derived | IOKit `IOBlockStorageDriver` "Statistics" | `Σ Δ"Bytes (Read)" / Δ time` over physical block devices, disk images excluded | fast tier |34| `disk.write` (`diskWrite`) | Disk write | bytes per second | derived | same | `Σ Δ"Bytes (Write)" / Δ time`, same exclusion | fast tier |35| `disk.free` (`diskFree`) | Startup volume available | bytes | measured | `URLResourceValues.volumeAvailableCapacityForImportantUsage` | Available space of the volume flagged as root file system; includes purgeable space | read on the slow tier (30 s), stored on every tick with the last reading |3637Default fast tier: 2 s while a window is visible, 5 s with only the menu bar, doubled on battery when the battery saver is on (see [telemetry](../architecture/telemetry.md)).3839There is no percentage convention for throughput. Volume usage is shown as `used / total` where `used = total − available`.4041## Volumes4243`DiskCollector.volumes()` enumerates `FileManager.mountedVolumeURLs(includingResourceValuesForKeys:options: [.skipHiddenVolumes])` and skips volumes whose total capacity is zero.4445| Field | Source | Meaning |46|---|---|---|47| `name` | `volumeName` | Display name |48| `mountPoint` | URL path | Also the row identity |49| `format` | `volumeLocalizedFormatDescription` | e.g. APFS |50| `total` | `volumeTotalCapacity` | Size of the volume (of the container for APFS) |51| `free` | `volumeAvailableCapacity` | Space free right now, without purging anything |52| `available` | `max(volumeAvailableCapacityForImportantUsage, free)` | Space macOS says is available for important usage: free space plus what it can purge |53| `isRoot` | `volumeIsRootFileSystem` | The startup volume |54| `isInternal`, `isRemovable`, `isReadOnly` | resource values | Shown as tags |55| `isNetwork` | `!volumeIsLocal` | Network share |56| `bsdName` | `DADiskGetBSDName` | e.g. `disk3s1`; absent for network volumes |57| `containerBSDName` | `DADiskCopyWholeDisk` → BSD name | The whole disk or APFS container |58| `deviceModel`, `connection` | `DADiskCopyDescription` | Device model, protocol |5960### "Available" versus "free"6162Both are shown for every volume: "*X* available of *Y*" and "*Z* free without purging".6364- **Free** is what the file system has unallocated now.65- **Available** additionally counts purgeable space (local snapshots, caches the system may delete, optimised storage). It is the figure Finder shows and the one that matters when deciding whether something fits.66- `disk.free` — despite its key — stores the **available** figure of the startup volume. Its display name is "Startup volume available", and its catalogue method says "includes purgeable space". The default alert ("below 20 GB") and the `diskExhaustion` finding work on this series.6768`max(important, free)` guards against volumes for which the "important usage" key returns zero (some external and network volumes).6970## Physical activity7172`DiskCollector.activity(now:)` iterates `IOBlockStorageDriver` services.7374| `PhysicalDisk` field | Source |75|---|---|76| `bsdName` | Child media entry, `BSD Name` |77| `size` | Child media entry, `Size` |78| `model` | Parent device `Device Characteristics["Product Name"]`; "Disk Image" for virtual devices; the BSD name as a last resort |79| `mediumType` | `Device Characteristics["Medium Type"]` (e.g. solid state) |80| `interconnect` | `Protocol Characteristics["Physical Interconnect"]` |81| `isInternal` | `Protocol Characteristics["Physical Interconnect Location"] == "Internal"` |82| `isDiskImage` | Interconnect is `Virtual Interface` |83| `totalBytesRead`, `totalBytesWritten` | `Statistics["Bytes (Read)"]`, `["Bytes (Write)"]` — cumulative since boot (or since the device attached) |84| `readRate`, `writeRate` | `DiskMath.rates`: `Δ bytes / Δ time` |85| `readOpsRate`, `writeOpsRate` | `Δ "Operations (Read/Write)" / Δ time` — collected, not displayed |8687### Rate rules8889- `CounterMath.delta` treats the counters as 64-bit: a decrease is a **reset** (device detached and re-attached), and the rate for that interval is `nil`, not a spike (`detachedAndReattachedDiskGivesNoRate`).90- A device seen for the first time has no rate until its second sample.91- The machine totals are `nil` (nothing stored) until at least one non-image device has produced a rate.92- Elapsed time is monotonic and shared by all devices of one sample.9394## Displayed values9596Disk page (`DiskView`):9798| Card | Content |99|---|---|100| Volumes | Per volume: name, tags (Startup, Read-only, Removable), "available of total", usage meter (turns to the danger colour above 90 % used), format, mount point, BSD name and container, connection, "free without purging" |101| Throughput | Read and write readouts and a two-series live chart |102| Available space, startup volume | Readout ("Includes space macOS can purge") and live chart |103| Block devices | Device, model, connection and medium, size, read rate, write rate, total read, total written; disk images shown dimmed; note "Totals count from the last restart." |104| Not available | SSD health / wear / temperature; per-process disk throughput |105106Elsewhere: dashboard "Storage" widget (first three volumes) and "Disk activity" widget, menu bar "Disk" indicator (R/W), History, Storage Analysis and System Overview reports.107108Per-process cumulative disk bytes (`ri_diskio_bytesread`, `ri_diskio_byteswritten`) appear in the Processes inspector as "Read from disk" / "Written to disk" for the user's own processes.109110## Quality classes111112- `derived` — read and write rates.113- `measured` — available space, as reported by the system.114115## Limitations116117- **Network and non-block volumes have no activity.** Traffic to a network share appears in [network](network.md) metrics, not here.118- **Throughput is at the block layer.** It includes everything the device does (paging, snapshots, Spotlight, other users), not only file I/O of visible apps.119- **"Available" is a system estimate of reclaimable space**; purging is at macOS's discretion and may not happen immediately.120- **`disk.free` tracks only the startup volume.** Other volumes are shown live but have no history and no alert.121- **Slow-tier granularity.** Available space is re-read every 30 s by default; the series repeats the last reading in between.122- **Depends on IORegistry layout.** A storage driver that publishes no `Statistics` dictionary is not listed.123- **Hidden volumes are skipped** (`.skipHiddenVolumes`): system volumes such as Preboot or Recovery do not appear.124125## Deliberately not shown126127| Item | Reason |128|---|---|129| SSD health, wear level, SMART attributes, SSD temperature | NVMe SMART data is only reachable through privileged or private interfaces. ORIX Monitor "shows none rather than guess". |130| Per-process disk throughput (rates) | Only cumulative per-process bytes are available; no rate ranking is built from them. |131| Per-volume throughput | The kernel counts I/O per block device, not per volume. |132| A sum of volume capacities | It would double-count shared APFS containers. |133| Disk-image I/O in the totals | Already counted on the backing device. |134| Read/write operation rates (IOPS) and latency | Operation counts are collected by `DiskMath` but not surfaced; I/O latency is not collected at all. |135| File-level usage ("what takes space") | Out of scope; findings point to System Settings › General › Storage. |136
Files main
Menu

Theme