Local Trace API

• 

  Overview page

Inspiration

Local AI changed what a Mac's disk is for. Ollama, LM Studio, and Hugging Face fill hidden folders with ten-gigabyte model files, and you find out the disk is full when a download fails. macOS gives you a pie chart and a df that is wrong for APFS. Nothing tells you who is consuming the space, how fast a specific volume actually is, or that something went wrong while you were away. I wanted the tool I'd want running on my own machine: one that watches what matters and never reports something it can't back up.

What it does

LocalTrace is a local, no-root storage monitor for Macs running AI workloads. It watches real model directories through FSEvents, reports capacity correctly for APFS shared containers, measures throughput both passively (device counters) and actively (a bounded write/flush/read probe on a chosen APFS or NFS mount, so the GB/s number describes the filesystem), breaks usage down by owning account with each account's largest files, reports SMART, seal state, snapshots, and native APFS quotas, and covers NFS with a sourced answer on pNFS. Two alert rules (rapid file growth, capacity pressure) post a macOS notification and write a JSON Lines log, then link each alert to the file events behind it.

Every metric carries a state: available, partial, warming_up, unavailable, or error. Missing SMART is never "healthy."

How I built it

Python + FastAPI on loopback, one collector per native macOS interface (diskutil, nfsstat, quota, tmutil, system_profiler, FSEvents, psutil), each owning its capability state. Slow collectors run in background threads and serve their newest result so one-second polling never blocks. React frontend with a strict normalizer that rejects unknown response shapes. A Makefile drives everything, and CI runs 123 backend tests plus a smoke script on a real macOS runner that executes every utility and the throughput probe.

Challenges

• APFS capacity math. Sibling volumes share a container, so per-volume free space double-counts. Alerts use container total minus available.
• Filesystem-specific GB/s. macOS only counts bytes per device, so the number has to be measured: F_FULLFSYNC so write includes stable storage, F_NOCACHE so read skips the buffer cache, and each result records whether both were engaged.
• pNFS. The macOS client doesn't implement it. The right answer was to say so with sources.
• Delivery off the alerting thread. osascript is slow; alerts now queue to a worker with per-sink outcomes, so the UI can't say "on" for a sink that just failed.
• Ownership isn't authorship. The tool knows who owns a file, not who wrote it, and says exactly that.

I used Claude as a pair programmer across the 24 hours. It let me cover every criterion; it also produced bugs I caught in review, including a delivery status that only rendered when there were zero alerts. Treating AI output as a draft to test, not a result, is what made the volume safe.

What I learned

More about APFS than I expected: shared containers, seal state, native volume quotas, why st_blocks is only an upper bound when clones share extents. That a bounded budget beats a clever algorithm when the input is a 200 GB model cache. And that the most valuable line in a monitoring tool is the one that admits what it doesn't know.

What's next

Near term: a sustained-I/O rule, an owner-share rule, and SQLite history for trends and capacity runway. Medium term: webhook/email sinks, on-demand diskutil verifyVolume, SATA/USB health, multi-account quota visibility. Longer term: independent remote NFS validation, pNFS detection if Apple ships it, process-level attribution via Endpoint Security, and a Swift menu-bar agent on the same API.

Built With

• apfs
• fastapi
• fsevents
• github-actions
• macos
• nfs
• psutil
• pydantic
• pytest
• python
• react
• typescript
• vite