Detecting and Diagnosing iOS App Lag with RunLoop Monitoring

Background Introduction

When users encounter poor experience in an app, the issues often appear in scenarios like black/white screen delays on complex pages, occasional list scrolling stutter, image loading lag, and UI freeze during intensive network requests. These problems affect both low‑end and high‑end devices, and prolonged main‑thread blockage severely degrades user experience.

Root Causes of Main‑Thread Blocking

Heavy UI rendering : Complex view hierarchies and rich mixed content increase layout and drawing workload beyond a single refresh cycle.

Synchronous network requests on the main thread : The app must wait for network data, blocking all user interactions.

Large file I/O : Direct reads/writes to disk or database on the main thread consume significant time.

High‑load computation : Executing heavy algorithms on the main thread keeps the CPU busy.

Improper thread locks : Waiting for locks can suspend the main thread and even cause deadlocks.

Mainstream Lag‑Monitoring Schemes

Ping thread scheme – a background thread periodically pings the main thread and checks a flag to detect delays.

FPS monitoring – measures frame rate to infer UI smoothness, but cannot pinpoint the exact bottleneck.

RunLoop monitoring – observes the main‑thread RunLoop state changes to capture millisecond‑level blockages.

Ping Thread Scheme

Create a monitoring thread.

Periodically dispatch a simple task to the main thread and set a flag.

If the flag remains set after a timeout, the main thread is considered blocked.

Capture and report the stack trace.

The Ping scheme is simple but has lower precision and may miss some blocks.

FPS Monitoring Scheme

iOS devices refresh at 60 Hz (or 120 Hz on newer models). By counting CADisplayLink callbacks per second, developers can gauge UI smoothness, yet low FPS alone does not guarantee detection of specific lag sources.

RunLoop Monitoring Scheme

This approach registers a CFRunLoopObserver to listen for RunLoop state changes ( kCFRunLoopBeforeTimers, kCFRunLoopBeforeSources, kCFRunLoopAfterWaiting, etc.). When the observer receives a “before” event, it marks running = YES and records startTime. When a “after waiting” or “exit” event occurs, it clears the flag. A background thread continuously checks the flag and timestamps; if the elapsed time exceeds a threshold, a lag is detected.

Implementation Details

Register the observer on the main RunLoop.

Create a monitoring thread to read running and startTime.

When running stays true beyond the threshold, capture the main‑thread stack.

Use KSCrash to obtain symbolicated stacks, enabling precise code‑level diagnosis.

Stack Extraction and Most‑Expensive Stack Identification

Stacks are sampled every 50 ms and stored in a circular buffer. The most time‑consuming stack is identified by:

Comparing top‑frame functions – stacks with different top frames are distinct.

Counting consecutive repetitions – more repetitions imply longer execution time.

If repetitions are equal, the most recent stack is chosen.

Annealing (Back‑off) Algorithm

To avoid excessive overhead during prolonged lag, the monitoring interval follows a Fibonacci back‑off: identical stacks cause the interval to increase, while a new stack resets it, reducing CPU usage while still capturing critical events.

Performance Overhead Evaluation

Two app builds were tested on an iPhone 12 Pro (iOS 18.7): one with lag monitoring disabled and one with it fully enabled. CPU usage without lag increased by only ~0.33 % when monitoring was active, and the overhead was negligible during normal operation.

Conclusion

The RunLoop‑based monitoring provides precise detection of main‑thread blockages with minimal performance impact, making it suitable for production environments. It has been integrated into Alibaba Cloud ARMS iOS SDK, and developers can refer to the official integration guide for implementation.

For more details, see the ARMS iOS integration documentation .