debugging-instruments

dpearson2699/swift-ios-skillsDeveloper ToolsAudit passedSnapshot 7f0285af8777

Installs: 0

Summary

Debug iOS apps and profile performance using LLDB, the interactive Memory Graph Debugger, and Instruments. Use for crashes, retain-cycle inspection, hangs, build failures, and generic CPU, memory, energy, or network profiling. Use ios-memgraph-analysis for .memgraph capture, leaks CLI ownership paths, or persistent heap growth; use ios-ettrace-performance for ETTrace capture and JSON.

SKILL.md

Debugging and Instruments

Keep interactive graph and Instruments triage here. Route detailed .memgraph command-line ownership/growth analysis and ETTrace work to their focused skills.

LLDB Debugging
Memory Debugging
Hang Diagnostics
Build Failure Triage
Instruments Overview
Common Mistakes
Review Checklist
References

LLDB Debugging

Start with a small, repeatable workflow:

Reproduce in a Debug build and stop at the narrowest useful breakpoint.
Inspect locals without executing code, then capture the current stack.
Move to the relevant frame or thread and verify the failing state.
Add a condition or watchpoint only when the bad transition is still unclear.

(lldb) br set -f ViewModel.swift -l 42     # Stop at file and line
(lldb) v myLocal                           # Inspect without executing code
(lldb) po myObject                         # Use debugDescription when needed
(lldb) bt all                              # Capture every thread's backtrace
(lldb) frame select 3                      # Inspect a relevant frame
(lldb) br modify 1 -c "count > 10"         # Narrow a noisy breakpoint
(lldb) w set v self.score                  # Stop on an unexpected write

Use v over po when you only need a local variable value — it does not execute code and cannot trigger side effects. Expression evaluation can execute or mutate program state, and hardware watchpoints are scarce, so use both deliberately.

// LEAK — closure holds strong reference to self
class ProfileViewModel {
    var onUpdate: (() -> Void)?

    func startObserving() {
        onUpdate = {
            self.refresh()  // strong capture of self
        }
    }
}

// FIXED — use [weak self]
func startObserving() {
    onUpdate = { [weak self] in
        self?.refresh()
    }
}

// LEAK — strong delegate creates a cycle
protocol DataDelegate: AnyObject {
    func didUpdate()
}

class DataManager {
    var delegate: DataDelegate?  // should be weak
}

// FIXED — weak delegate
class DataManager {
    weak var delegate: DataDelegate?
}

// LEAK — Timer.scheduledTimer retains its target
timer = Timer.scheduledTimer(
    timeInterval: 1.0, target: self,
    selector: #selector(tick), userInfo: nil, repeats: true
)

// FIXED — use closure-based API with [weak self]
timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
    self?.tick()
}

# Inspect an exported memory graph from Xcode or Instruments
leaks MyApp.memgraph

import os

let signposter = OSSignposter(subsystem: "com.example.app", category: "DataLoad")

func loadData() async {
    let state = signposter.beginInterval("loadData")
    let result = await fetchFromNetwork()
    signposter.endInterval("loadData", state)
    process(result)
}

Cause	Symptom	Fix
Synchronous I/O on main thread	Network/file reads block UI	Move to `Task { }` or background actor
Lock contention	Main thread waiting on a lock held by background work	Use actors or reduce lock scope
Layout thrashing	Repeated `layoutSubviews` calls	Batch layout changes, avoid forced layout
JSON parsing large payloads	UI freezes during data load	Parse on a background thread
Synchronous image decoding	Scroll jank on image-heavy lists	Use `AsyncImage` or decode off main thread

# Common: version conflict
error: Dependencies could not be resolved because root depends on 'Package' 1.0.0..<2.0.0

# Fix: check Package.resolved and update version ranges
# Reset package caches if needed:
rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf .build
swift package resolve

Error	Check
`No such module 'Foo'`	Target membership, import paths, framework search paths
`Undefined symbol`	Linking phase missing framework, wrong architecture
`duplicate symbol`	Two targets define same symbol; check for ObjC naming collisions

Template	Use When
Time Profiler	CPU is high, UI feels slow, need to find hot code paths
Allocations	Memory grows over time, need to track object lifetimes
Leaks	Suspect retain cycles or abandoned objects
Network	Inspecting HTTP request/response timing and payloads
SwiftUI	Profiling view body evaluations and update frequency
Animation Hitches / Core Animation instruments	Frame drops, hitches, blending, and commit/render work
Power Profiler	Battery drain, thermal pressure, background energy impact
File Activity	Excessive disk I/O, slow file operations
System Trace	Thread scheduling, syscalls, virtual memory faults

# Record a trace from the command line
xcrun xctrace record --device "My iPhone" \
    --template "Time Profiler" \
    --instrument "Allocations" \
    --output profile.trace \
    --launch -- /path/to/MyApp.app

# Export trace data as XML for automated analysis
xcrun xctrace export --input profile.trace --xpath '/trace-toc/run/data/table'

# List available templates
xcrun xctrace list templates

# List connected devices
xcrun xctrace list devices

// WRONG — unstructured and not filterable by subsystem/category
print("user tapped button, state: \(viewModel.state)")
print("network response: \(data)")

// CORRECT — structured logging with Logger
import os

let logger = Logger(subsystem: "com.example.app", category: "UI")

logger.debug("Button tapped, state: \(viewModel.state, privacy: .public)")
logger.info("Network response received, bytes: \(data.count)")

// WRONG — open Memory Graph without enabling Malloc Stack Logging
// Result: leaked objects visible but no allocation backtrace

// CORRECT — enable BEFORE running:
// Scheme > Run > Diagnostics > check "Malloc Stack Logging: All Allocations"
// Then run, reproduce the leak, and open Memory Graph

// WRONG — profiling with Debug build, debugging with Release build
// Debug builds: extra runtime checks distort perf measurements
// Release builds: variables show as "<optimized out>" in debugger

// CORRECT approach:
// Debugging: use Debug configuration (full symbols, no optimization)
// Profiling: use Release configuration (realistic performance)

// WRONG — breakpoint on line inside loop, stops 10,000 times
for item in items {
    process(item)  // breakpoint here stops on EVERY item
}

// CORRECT — use a conditional breakpoint:
// (lldb) br set -f MyFile.swift -l 42 -c "item.id == targetID"
// Or in Xcode: right-click breakpoint > Edit > add Condition

// WRONG — ignoring TSan warning about concurrent access
var cache: [String: Data] = [:]  // accessed from multiple threads

// CORRECT — protect shared mutable state
actor CacheActor {
    var cache: [String: Data] = [:]

    func get(_ key: String) -> Data? { cache[key] }
    func set(_ key: String, _ value: Data) { cache[key] = value }
}

debugging-instruments

Summary

SKILL.md

Debugging and Instruments

Contents

LLDB Debugging

Memory Debugging

Memory Graph Debugger Workflow

Common Retain Cycle Patterns

Instruments: Allocations and Leaks

Malloc Stack Logging

Hang Diagnostics

Identifying Main Thread Hangs

Using the Time Profiler

Common Hang Causes

Build Failure Triage

Reading Compiler Diagnostics

SPM Dependency Resolution

Module Not Found / Linker Errors

Instruments Overview

Template Selection Guide

xctrace CLI for CI Profiling

Common Mistakes

DON'T: Use print() for debugging instead of os.Logger

DON'T: Forget to enable Malloc Stack Logging before memory debugging

DON'T: Debug optimized code expecting full variable visibility

DON'T: Stop on every loop iteration without conditional breakpoints

DON'T: Ignore Thread Sanitizer warnings

Review Checklist

References

Related skills