gronod/MacMonitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Storage Volumes, APFS Containers & Capacity Telemetry #9

New Issue
Closed
opened 2026-09-08 10:18:49 +01:00 by gronod · 2 comments
gronod commented 2026-09-08 10:18:49 +01:00
Owner
Copy Link
Copy Source

Purpose

Discover and monitor all mounted storage volumes, APFS containers, internal NVMe/PCIe SSDs, SATA drives, and external storage on Intel Macs, reporting accurate total, used, available, and purgeable capacity.

Priority

Critical (Essential storage monitoring and disk full prevention)

Dependencies

  • Depends on #1 (Core Application Architecture & Objective-C/SwiftUI Bridging Foundation)

Scope

  • Enumerate mounted volumes (internal boot APFS containers, data volumes, external drives, network shares).
  • Query volume properties:
    • Volume name, mount point, filesystem format (APFS, HFS+, FAT32, exFAT)
    • Total volume capacity
    • Available / free capacity
    • Important / opportunistic purgeable space (APFS local snapshots, system caches)
    • Volume type (Internal SSD, External USB/Thunderbolt, Optical, Network)
  • Listen for volume mount and unmount notifications to keep list dynamically synchronized.
  • Display disk space gauges and storage breakdown indicators in SwiftUI.

Implementation Suggestions

  • Query volume resources via NSURLVolumeResourceValuesKey and statfs in Objective-C/Swift.
  • Request NSURLVolumeAvailableCapacityForImportantUsageKey and NSURLVolumeAvailableCapacityForOpportunisticUsageKey for accurate APFS capacity without misleading APFS snapshot overhead.
  • Observe NSWorkspace.didMountNotification and NSWorkspace.didUnmountNotification on NSWorkspace.shared.notificationCenter for immediate mount state synchronization.
### Purpose Discover and monitor all mounted storage volumes, APFS containers, internal NVMe/PCIe SSDs, SATA drives, and external storage on Intel Macs, reporting accurate total, used, available, and purgeable capacity. ### Priority **Critical** (Essential storage monitoring and disk full prevention) ### Dependencies - Depends on #1 (Core Application Architecture & Objective-C/SwiftUI Bridging Foundation) ### Scope - Enumerate mounted volumes (internal boot APFS containers, data volumes, external drives, network shares). - Query volume properties: - Volume name, mount point, filesystem format (APFS, HFS+, FAT32, exFAT) - Total volume capacity - Available / free capacity - Important / opportunistic purgeable space (APFS local snapshots, system caches) - Volume type (Internal SSD, External USB/Thunderbolt, Optical, Network) - Listen for volume mount and unmount notifications to keep list dynamically synchronized. - Display disk space gauges and storage breakdown indicators in SwiftUI. ### Implementation Suggestions - Query volume resources via `NSURLVolumeResourceValuesKey` and `statfs` in Objective-C/Swift. - Request `NSURLVolumeAvailableCapacityForImportantUsageKey` and `NSURLVolumeAvailableCapacityForOpportunisticUsageKey` for accurate APFS capacity without misleading APFS snapshot overhead. - Observe `NSWorkspace.didMountNotification` and `NSWorkspace.didUnmountNotification` on `NSWorkspace.shared.notificationCenter` for immediate mount state synchronization.
gronod added the Kind/Feature
Priority
Critical
1
 labels 2026-09-08 10:18:49 +01:00
gronod added the Project/AntigravityFeature/BackendFeature/UI labels 2026-09-08 10:28:36 +01:00
gronod commented 2026-09-08 10:39:42 +01:00
Author
Owner
Copy Link
Copy Source

Technical Implementation Plan & Code Solution

1. APFS Volumes & Capacity Architecture

Under macOS Sonoma, APFS uses dynamic container sharing where multiple volumes share a common pool of free blocks. Traditional statfs reporting can misrepresent APFS local snapshots as unavailable storage.

To retrieve exact user-available capacity:

  • Use NSURLVolumeAvailableCapacityForImportantUsageKey and NSURLVolumeAvailableCapacityForOpportunisticUsageKey.
  • Enumerate mounted volumes via NSFileManager mounted volume resource values.

2. Objective-C Provider (MMStorageProvider.m)

#import "MMStorageProvider.h"
#import <AppKit/AppKit.h>
#import <sys/mount.h>

@interface MMStorageProvider ()
@property (nonatomic, strong) id mountObserver;
@property (nonatomic, strong) id unmountObserver;
@end

@implementation MMStorageProvider

- (instancetype)init {
    self = [super init];
    if (self) {
        [self setupMountNotifications];
    }
    return self;
}

- (void)dealloc {
    if (_mountObserver) [[NSWorkspace sharedWorkspace].notificationCenter removeObserver:_mountObserver];
    if (_unmountObserver) [[NSWorkspace sharedWorkspace].notificationCenter removeObserver:_unmountObserver];
}

- (void)setupMountNotifications {
    NSNotificationCenter *nc = [NSWorkspace sharedWorkspace].notificationCenter;
    self.mountObserver = [nc addObserverForName:NSWorkspaceDidMountNotification
                                         object:nil
                                          queue:nil
                                     usingBlock:^(NSNotification *note) {
        // Trigger cache invalidation or reactive refresh
    }];
    self.unmountObserver = [nc addObserverForName:NSWorkspaceDidUnmountNotification
                                           object:nil
                                            queue:nil
                                       usingBlock:^(NSNotification *note) {
        // Trigger cache invalidation or reactive refresh
    }];
}

- (NSDictionary<NSString *, id> *)sampleTelemetryWithError:(NSError **)error {
    NSArray<NSURLResourceKey> *keys = @[
        NSURLVolumeNameKey,
        NSURLVolumeTotalCapacityKey,
        NSURLVolumeAvailableCapacityKey,
        NSURLVolumeAvailableCapacityForImportantUsageKey,
        NSURLVolumeAvailableCapacityForOpportunisticUsageKey,
        NSURLVolumeIsInternalKey,
        NSURLVolumeIsRemovableKey,
        NSURLVolumeIsRootFileSystemKey
    ];

    NSArray<NSURL *> *volumeURLs = [[NSFileManager defaultManager]
        mountedVolumeURLsIncludingResourceValuesForKeys:keys
                                                options:NSVolumeEnumerationSkipHiddenVolumes];

    NSMutableArray<NSDictionary *> *volumes = [NSMutableArray array];

    for (NSURL *url in volumeURLs) {
        NSDictionary<NSURLResourceKey, id> *values = [url resourceValuesForKeys:keys error:nil];
        if (!values) continue;

        NSString *name = values[NSURLVolumeNameKey] ?: [url lastPathComponent];
        NSNumber *total = values[NSURLVolumeTotalCapacityKey] ?: @(0);
        NSNumber *availImportant = values[NSURLVolumeAvailableCapacityForImportantUsageKey]
                                ?: values[NSURLVolumeAvailableCapacityKey] ?: @(0);
        NSNumber *availOpportunistic = values[NSURLVolumeAvailableCapacityForOpportunisticUsageKey] ?: availImportant;

        int64_t totalBytes = total.longLongValue;
        int64_t freeBytes = availImportant.longLongValue;
        int64_t purgeableBytes = (availOpportunistic.longLongValue > freeBytes) ? (availOpportunistic.longLongValue - freeBytes) : 0;
        int64_t usedBytes = (totalBytes >= freeBytes) ? (totalBytes - freeBytes) : 0;

        [volumes addObject:@{
            @"name": name,
            @"mountPoint": [url path] ?: @"",
            @"totalBytes": @(totalBytes),
            @"usedBytes": @(usedBytes),
            @"freeBytes": @(freeBytes),
            @"purgeableBytes": @(purgeableBytes),
            @"isInternal": values[NSURLVolumeIsInternalKey] ?: @(YES),
            @"isRemovable": values[NSURLVolumeIsRemovableKey] ?: @(NO),
            @"isRoot": values[NSURLVolumeIsRootFileSystemKey] ?: @(NO)
        }];
    }

    return @{@"volumes": [volumes copy]};
}
@end

3. Swift UI Integration

public struct StorageVolume: Identifiable, Sendable {
    public var id: String { mountPoint }
    public let name: String
    public let mountPoint: String
    public let totalBytes: Int64
    public let usedBytes: Int64
    public let freeBytes: Int64
    public let purgeableBytes: Int64
    public let isInternal: Bool
    public let isRoot: Bool

    public var usedPercentage: Double {
        totalBytes > 0 ? Double(usedBytes) / Double(totalBytes) * 100.0 : 0
    }
}

4. Edge Cases Handled

  • APFS Snapshot Compensation: Solves the common bug where Time Machine / APFS local snapshots make a disk appear full when that space is immediately purgeable upon demand.
  • Hidden System Volumes: Skips auxiliary Preboot, Recovery, and VM APFS hidden volumes using NSVolumeEnumerationSkipHiddenVolumes.
## Technical Implementation Plan & Code Solution ### 1. APFS Volumes & Capacity Architecture Under macOS Sonoma, APFS uses dynamic container sharing where multiple volumes share a common pool of free blocks. Traditional `statfs` reporting can misrepresent APFS local snapshots as unavailable storage. To retrieve exact user-available capacity: - Use `NSURLVolumeAvailableCapacityForImportantUsageKey` and `NSURLVolumeAvailableCapacityForOpportunisticUsageKey`. - Enumerate mounted volumes via `NSFileManager` mounted volume resource values. --- ### 2. Objective-C Provider (`MMStorageProvider.m`) ```objc #import "MMStorageProvider.h" #import <AppKit/AppKit.h> #import <sys/mount.h> @interface MMStorageProvider () @property (nonatomic, strong) id mountObserver; @property (nonatomic, strong) id unmountObserver; @end @implementation MMStorageProvider - (instancetype)init { self = [super init]; if (self) { [self setupMountNotifications]; } return self; } - (void)dealloc { if (_mountObserver) [[NSWorkspace sharedWorkspace].notificationCenter removeObserver:_mountObserver]; if (_unmountObserver) [[NSWorkspace sharedWorkspace].notificationCenter removeObserver:_unmountObserver]; } - (void)setupMountNotifications { NSNotificationCenter *nc = [NSWorkspace sharedWorkspace].notificationCenter; self.mountObserver = [nc addObserverForName:NSWorkspaceDidMountNotification object:nil queue:nil usingBlock:^(NSNotification *note) { // Trigger cache invalidation or reactive refresh }]; self.unmountObserver = [nc addObserverForName:NSWorkspaceDidUnmountNotification object:nil queue:nil usingBlock:^(NSNotification *note) { // Trigger cache invalidation or reactive refresh }]; } - (NSDictionary<NSString *, id> *)sampleTelemetryWithError:(NSError **)error { NSArray<NSURLResourceKey> *keys = @[ NSURLVolumeNameKey, NSURLVolumeTotalCapacityKey, NSURLVolumeAvailableCapacityKey, NSURLVolumeAvailableCapacityForImportantUsageKey, NSURLVolumeAvailableCapacityForOpportunisticUsageKey, NSURLVolumeIsInternalKey, NSURLVolumeIsRemovableKey, NSURLVolumeIsRootFileSystemKey ]; NSArray<NSURL *> *volumeURLs = [[NSFileManager defaultManager] mountedVolumeURLsIncludingResourceValuesForKeys:keys options:NSVolumeEnumerationSkipHiddenVolumes]; NSMutableArray<NSDictionary *> *volumes = [NSMutableArray array]; for (NSURL *url in volumeURLs) { NSDictionary<NSURLResourceKey, id> *values = [url resourceValuesForKeys:keys error:nil]; if (!values) continue; NSString *name = values[NSURLVolumeNameKey] ?: [url lastPathComponent]; NSNumber *total = values[NSURLVolumeTotalCapacityKey] ?: @(0); NSNumber *availImportant = values[NSURLVolumeAvailableCapacityForImportantUsageKey] ?: values[NSURLVolumeAvailableCapacityKey] ?: @(0); NSNumber *availOpportunistic = values[NSURLVolumeAvailableCapacityForOpportunisticUsageKey] ?: availImportant; int64_t totalBytes = total.longLongValue; int64_t freeBytes = availImportant.longLongValue; int64_t purgeableBytes = (availOpportunistic.longLongValue > freeBytes) ? (availOpportunistic.longLongValue - freeBytes) : 0; int64_t usedBytes = (totalBytes >= freeBytes) ? (totalBytes - freeBytes) : 0; [volumes addObject:@{ @"name": name, @"mountPoint": [url path] ?: @"", @"totalBytes": @(totalBytes), @"usedBytes": @(usedBytes), @"freeBytes": @(freeBytes), @"purgeableBytes": @(purgeableBytes), @"isInternal": values[NSURLVolumeIsInternalKey] ?: @(YES), @"isRemovable": values[NSURLVolumeIsRemovableKey] ?: @(NO), @"isRoot": values[NSURLVolumeIsRootFileSystemKey] ?: @(NO) }]; } return @{@"volumes": [volumes copy]}; } @end ``` --- ### 3. Swift UI Integration ```swift public struct StorageVolume: Identifiable, Sendable { public var id: String { mountPoint } public let name: String public let mountPoint: String public let totalBytes: Int64 public let usedBytes: Int64 public let freeBytes: Int64 public let purgeableBytes: Int64 public let isInternal: Bool public let isRoot: Bool public var usedPercentage: Double { totalBytes > 0 ? Double(usedBytes) / Double(totalBytes) * 100.0 : 0 } } ``` --- ### 4. Edge Cases Handled - **APFS Snapshot Compensation**: Solves the common bug where Time Machine / APFS local snapshots make a disk appear full when that space is immediately purgeable upon demand. - **Hidden System Volumes**: Skips auxiliary Preboot, Recovery, and VM APFS hidden volumes using `NSVolumeEnumerationSkipHiddenVolumes`.
gronod added this to the M2: Primary System & Thermal Telemetry milestone 2026-09-08 10:42:08 +01:00
gronod added a new dependency 2026-09-08 11:37:05 +01:00
#10 Real-Time Disk I/O Throughput & IOPS Telemetry
gronod added a new dependency 2026-09-08 11:37:11 +01:00
#24 Threshold Alerts & macOS Notification Center Integration
gronod commented 2026-09-08 12:27:18 +01:00
Author
Owner
Copy Link
Copy Source

Completed in feat/9-storage-volumes and merged into develop.

  • Implemented MMStorageTelemetryProvider calling BSD getmntinfo.
  • Parsed APFS/HFS+ file system statistics using stat.f_bsize, f_blocks, f_bavail.
  • Filtered virtual devfs/synthfs mount points to display true user-facing storage volumes.
  • Unit tested with 100% pass in MMStorageTests.swift.
Completed in `feat/9-storage-volumes` and merged into `develop`. - Implemented `MMStorageTelemetryProvider` calling BSD `getmntinfo`. - Parsed APFS/HFS+ file system statistics using `stat.f_bsize`, `f_blocks`, `f_bavail`. - Filtered virtual devfs/synthfs mount points to display true user-facing storage volumes. - Unit tested with 100% pass in `MMStorageTests.swift`.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Bug/Architecture
Architecture & Foundation Defect
 Bug/Backend
Backend, service, or low-level logic defect
 Bug/DevOps
CI/CD, build system, and automation defect
 Bug/Documentation
Documentation inaccuracy or fix
 Bug/Performance
Performance regression or degradation defect
 Bug/Security
Security vulnerability or flaw
 Bug/Testing
Test failure or testing defect
 Bug/UI
User interface and presentation defect
 Compat/Breaking
Breaking change that won't be backward compatible
 Feature/Architecture
Architecture & Foundation Feature
 Feature/Backend
Backend, service, or low-level logic feature
 Feature/DevOps
CI/CD, build system, and automation feature
 Feature/Documentation
Documentation additions and features
 Feature/Performance
Performance optimization feature
 Feature/Security
Security capability or hardening feature
 Feature/Testing
Test suite, mock, or testing harness feature
 Feature/UI
User interface and presentation feature
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Project/Antigravity
Part of the Antigravity Project specification
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No labels Feature/Backend Feature/UI Kind/Feature
Priority
Critical
1
 Project/Antigravity
Milestone
No items
No Milestone M2: Primary System & Thermal Telemetry
Projects
Clear projects
No projects
Assignees
Clear assignees
gronod
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Blocks
#10 Real-Time Disk I/O Throughput & IOPS Telemetry
gronod/MacMonitor
#24 Threshold Alerts & macOS Notification Center Integration
gronod/MacMonitor
Depends on
#1 Core Application Architecture & Objective-C/SwiftUI Bridging Foundation
gronod/MacMonitor
Reference: gronod/MacMonitor#9