macOS runtime diagnostics

See what your app actually did during a run.

TraceRig captures file activity, logs, process events, and network behavior, then turns them into timelines, diffs, exports, and diagnostic insight.

Download for macOS View GitHub
Platform
macOS 13+
Stack
Swift, SwiftUI, SQLite3
Dependencies
No third-party runtime dependencies
TraceRig dashboard showing recent completed sessions, total tracked time, app count, and average duration.

The problem

Runtime failures rarely leave one clean breadcrumb trail.

Hard to reproduce

Startup failures, regressions, and intermittent macOS behavior often disappear before you can inspect them.

Signals are scattered

Logs, files, process trees, and sockets live in separate places, with separate tools and separate timelines.

Diffs need context

Developers need to compare a known-good run against a broken run and find the first meaningful divergence.

The solution

Capture a session. Inspect the timeline. Compare behavior.

TraceRig records what a target app does while it runs, normalizes events into a searchable model, and gives you a practical way to answer: what changed, what looked unusual, and what happened first?

Core features

Built from the project files, not marketing fog.

Capture

Runtime session capture

Select a running app by bundle ID. TraceRig stores baseline and final filesystem snapshots and tracks runtime events during the session.

Timeline

Event inspection

Filter a chronological event stream by process, file, log, network, or error. Event details include metadata and likely causal links.

Files

File activity visibility

FSEvents captures create, unlink, rename, and modify activity. Snapshot diffs surface created, deleted, modified, renamed, and unchanged files.

Logs

Unified log capture

TraceRig streams macOS unified logs for the target process and maps fault, error, default, and debug output into normalized events.

Processes

Process tracking

A live process tree follows descendant PIDs and emits EXEC and EXIT events as child processes appear or terminate.

Network

Network state and flow capture

Network probes observe TCP and UDP socket state. The current status also marks lifecycle-aware network flow capture as complete.

Compare

Session comparison

Compare completed sessions by file diff and behavior diff, including hosts, processes, actions, anomalies, and first divergence signals.

Insight

Anomalies, signatures, summaries

Completed milestones include explain-session summaries, anomaly scoring, deterministic behavior signatures, and an insight dashboard.

How it works

Three steps, no séance required.

  1. 01

    Capture a session

    Choose the target app, start capture, and let TraceRig collect runtime signals while the issue is reproduced.

  2. 02

    Inspect behavior

    Review the session overview, process tree, timeline filters, file activity, logs, and network observations.

  3. 03

    Compare and diagnose

    Compare clean and broken sessions, export JSON artifacts, and use summaries, anomalies, and divergence points to explain the run.

Screenshots

Current app UI

Captions describe what is visible in the supplied screenshots.

TraceRig Timeline screen with filter chips and NET and LOG events listed chronologically.
Timeline inspection with filters for process, file, log, network, and error events.
TraceRig Capture overview showing session ID, bundle ID, start time, watch paths, snapshot counts, event count, and snapshot diff summary.
Session overview showing metadata, event volume, baseline/final snapshots, and snapshot diff totals.
TraceRig Timeline screen filtered to FILE events showing create, unlink, rename, and modify entries with file paths.
File activity view focused on create, unlink, rename, and modify events.
TraceRig Diff screen comparing two sessions with modified files, size columns, and hash status.
Diff view comparing two completed sessions and surfacing modified files.
TraceRig Artifacts screen for exporting a selected completed session to JSON with data preview counts.
Artifacts export producing a structured JSON bundle for a completed session.
TraceRig Health screen showing Full Disk Access, Endpoint Security degraded mode, log, nettop, tcpdump, and dtrace checks.
Health checks showing required access and optional probe availability.

Use cases

Where TraceRig earns its keep

Debug app startup failures Find unexpected file writes Compare clean vs broken runs Investigate network or handshake failures Support QA regression analysis Explain “works on my machine” drift

Technical principles

Diagnostic-only by design.

macOS-native

Built with Swift, SwiftUI, CoreServices/FSEvents, unified logs, sysctl, lsof, SQLite3, and optional DTrace.

No traffic tampering

Phase 3 network constraints explicitly rule out packet modification, TLS bypass, MITM interception, and certificate injection.

Graceful degradation

Optional probes can be unavailable or restricted without breaking the rest of the capture pipeline.

Local project architecture

The app uses local persistence through SQLite repositories. TODO: confirm any broader local-first positioning before making stronger privacy claims.

Roadmap and current status

Implemented vs planned

Summarized from PROJECT_STATUS.md.

Completed

  • M1-M9: app skeleton, snapshots, process tracking, FSEvents, unified logs, network probes, diff view, JSON export, optional DTrace
  • M10-M12: event normalization, rule engine, causality engine
  • M13-M17: explain session, anomaly detection, behavior signature, behavior diff, insight dashboard
  • M18: network flow capture v1

Planned

  • M19: TLS Insight v1
  • M20: Handshake Timeline View
  • M21: Network Compare v1
  • M22: First Divergence Detector
  • M23: Network Anomaly Rules

Ready to inspect the run?

TraceRig gives macOS debugging a timeline, not a pile of clues.

Use it when logs alone are too flat, reproduction is slippery, and comparing sessions matters more than guessing.

Download for macOS View GitHub