Darwin PMDA Optional Metrics (Device Enumeration, Power, Scheduler, Advanced Network)

[tallpsmith]

Overview

This issue tracks the optional Wave 4 metrics from Darwin PMDA Phase 2 development. These metrics were deprioritized during initial Phase 2 implementation (PR #2442 and subsequent work) as they are either:

• Specialized/low-value use cases
• Blocked by root/entitlement requirements
• Nice-to-have inventory features

Phase 2 Status: ~92 metrics completed (88% of planned scope). Core functionality delivered.

---

Wave 4 Scope (~22 metrics)

1. Device Enumeration (Category 9) - ~6 metrics

Why It Matters: Hardware inventory, device health monitoring.

USB Devices

• hinv.nusb - USB device count
• usb.device.vendor - Vendor ID (per-device instance)
• usb.device.product - Product ID (per-device instance)
• usb.device.speed - Connection speed (per-device instance)

Thunderbolt Devices

• hinv.nthunderbolt - Thunderbolt device count
• thunderbolt.device.name - Device name (per-device instance)

API: IOKit IOUSBHostDevice and IOThunderboltDevice enumeration
Complexity: MEDIUM - IOKit enumeration pattern exists
Blocker: None, just low priority

---

2. Power Consumption (Category 3.3) - ~4 metrics

Why It Matters: Detailed power draw visibility for CPU/GPU/SoC.

• power.cpu.watts - CPU power draw (mW)
• power.gpu.watts - GPU power draw (mW)
• power.package.watts - SoC total power (mW)
• power.dram.watts - Memory power (mW)

API: IOReport framework
Complexity: HIGH
Blocker: ⚠️ Requires root privileges or entitlements - IOReport access is restricted

---

3. Scheduler Counters (Category 8) - ~3 metrics

Why It Matters: CPU scheduling efficiency, performance tuning (specialized use).

• kernel.sched.type - Scheduler type ("edge" on modern macOS)
• kernel.sched.recommended_cores - Recommended core mask
• kernel.pmi.count - Performance monitoring interrupts

API: sysctl (kern.sched, kern.monotonic.pmis)
Complexity: LOW - simple sysctl reads
Blocker: None, just specialized/low value

---

4. Advanced Network Metrics (Category 5.2-5.3) - ~9 metrics

Why It Matters: Advanced protocol diagnostics, network tuning visibility.

IGMP/Multicast Statistics

• network.igmp.version - IGMP version in use
• network.igmp.v1_enabled - IGMPv1 enabled
• network.igmp.v2_enabled - IGMPv2 enabled
• network.igmp.v3_enabled - IGMPv3 enabled

Advanced TCP Metrics

• network.tcp.sack_enabled - SACK algorithm enabled
• network.tcp.ecn_enabled - ECN enabled
• network.tcp.fastopen - TCP Fast Open state
• network.tcp.rtt_min - Minimum RTT observed
• network.tcp.delayed_ack - Delayed ACK count

API: sysctl (net.inet.igmp.*, net.inet.tcp.*, tcpstat structure)
Complexity: LOW-MEDIUM - sysctl pattern already established
Blocker: None, just low priority for most users

---

Implementation Notes

File Organization (Proposed)

src/pmdas/darwin/
├── devices.c        # NEW: USB/Thunderbolt enumeration
├── power.c          # EXTEND: Add IOReport power metrics
├── network.c        # EXTEND: Add IGMP/advanced TCP
└── resources.c      # EXTEND: Add scheduler sysctls

Platform Compatibility

• All metrics should gracefully degrade on Intel Macs
• Power metrics may fail without proper entitlements (return PM_ERR_APPVERSION)
• Device enumeration works identically on Apple Silicon and Intel

---

References

• Phase 2 Research Doc: darwin-pmda-phase2-research.md in development branch
• Completed Phase 2 Work: ~92 metrics across GPU, battery, thermal, disk/APFS, process I/O, IPv6
• IOKit Documentation: https://developer.apple.com/documentation/iokit
• Apple XNU Source: https://github.com/apple/darwin-xnu

---

Decision Point

These metrics were intentionally deprioritized because:

1. Core Phase 2 value delivered without them (88% completion)
2. Power metrics blocked by root requirement
3. Device enumeration is inventory-focused (not performance monitoring)
4. Scheduler/advanced network are niche use cases

Recommend: Leave as backlog unless specific user request emerges.