everettjf/AppleTrace
Free🍎Objective C Method Tracing Call Chart
FreeFree tier
About everettjf/AppleTrace
AppleTrace is a lightweight, embeddable Objective-C tracing toolkit for iOS and macOS apps. It captures execution timelines by either automatically hooking every objc_msgSend (via arm64 function rebinding) or via manually placed APTBeginSection/APTEndSection markers. The recorded trace fragments are merged using a Python CLI tool into a single trace.json file, which can be opened in Perfetto (ui.perfetto.dev) for detailed visualization of method call durations, thread names, counters, and async events. Designed for performance, it uses name interning, zero-allocation per-thread call stacks, and batched writing to minimize overhead. AppleTrace is open source (MIT license) and maintained on an as-needed basis.
Key Features
Automatic method tracing via objc_msgSend / objc_msgSendSuper2 rebinding on arm64, no source changes needed
Manual sections with APTBeginSection/APTEndSection and helpers (APTBegin/APTEnd/APTScopeSection) for targeted instrumentation
Rich event types: instant markers, counters (CPU, memory, FPS), async/flow events that cross threads and dispatch queues
Zero-allocation per-thread call stack, class/SEL name interning, and per-thread batched writing for low overhead on the hot path
Runtime filtering with class-prefix allow/deny lists (APPLETRACE_TRACE_CLASS_ALLOW / DENY)
Thread name reporting to Perfetto instead of bare thread IDs
Perfetto-first workflow: open trace.json directly in browser at ui.perfetto.dev
Python 3 CLI tooling (scripts/appletrace_cli.py) for merging and processing traces, with streaming support for large captures
Pros & Cons
Pros
- Low overhead tracing due to zero-allocation design and batched writes
- Works on real iOS/macOS devices without requiring jailbreak
- Produces standard trace.json viewable in Perfetto, a powerful open-source trace visualizer
- Supports both automatic (no code changes) and manual tracing approaches
- Rich event types including counters, async, and flow events for complex scenarios
- Open source (MIT license) with clear documentation and tutorial
Cons
- Automatic method tracing currently limited to arm64 architectures (iOS/macOS devices)
- Requires Python 3 tooling for merging trace fragments, adding a processing step
- Manual section markers must be added to source code, which may not be suitable for all projects
- Maintained as needed, so updates may be infrequent
- Only supports Objective-C (not Swift method tracing directly, though Swift can call ObjC methods)
Best For
Performance analysis of iOS/macOS apps: identify hotspots and long-running methodsDebugging threading and async behavior with cross-thread async/flow eventsProfiling CPU, memory, or FPS counters over time during app executionInstrumenting specific code regions with manual sections for focused tracingRuntime method call visualization without modifying source code (via automatic hooking)
FAQ
What is AppleTrace?
AppleTrace is a lightweight, embeddable Objective-C tracing toolkit for iOS/macOS that captures execution timelines and produces trace.json files viewable in Perfetto.
How does AppleTrace work?
You instrument your app either manually with APTBeginSection/APTEndSection markers or automatically by hooking every objc_msgSend. Captured trace fragments are merged by a Python CLI into a single trace.json, which you open in Perfetto.
Is AppleTrace free?
Yes, AppleTrace is open source under the MIT license and is free to use.
What platforms does AppleTrace support?
AppleTrace supports iOS and macOS applications. Automatic method tracing works on arm64 devices.
Can I trace Swift code?
AppleTrace is designed for Objective-C method calls. Swift code can be traced if it calls Objective-C methods or is marked with @objc, but pure Swift method calls are not traced.