Detecting and Solving iOS App Lag: Inside WeChat’s Real‑Time Freeze Monitoring

Introduction

During early iOS WeChat development we frequently received feedback such as “My WeChat is stuck on the main screen and cannot be swiped” or “WeChat freezes briefly when switching from background to foreground”. These issues share a common symptom: the UI becomes unresponsive for a period of time and cannot be reproduced even with the user’s interaction trace.

We call this a “lag” problem. To locate it precisely, WeChat launched a lag‑monitoring system in September 2014. Over the years the system has been refined and is now shared here.

What Is Lag?

Lag occurs when the UI does not respond or rendering becomes sticky, which happens because the main thread is blocked.

Typical causes of main‑thread blockage include:

Heavy I/O on the main thread (e.g., writing large amounts of data directly).

Heavy computation on the main thread (inefficient algorithms).

Complex UI drawing that takes a long time.

Waiting for a lock held by another thread.

Capturing the main‑thread stack at the moment of lag reveals exactly which function and line are blocked, enabling targeted fixes.

Principle

iOS/macOS apps run a RunLoop on the main thread. Observers can be attached to the RunLoop’s entry and exit points to obtain the thread’s state.

Matrix lag monitoring adds observers at the very beginning and end of the RunLoop to capture start and end states. A secondary thread checks the main‑thread state periodically; if the RunLoop runs longer than a threshold, a lag is recorded.

The current threshold is 2 seconds and the checking interval is 1 second. When a lag is detected, the current thread snapshot is saved. If CPU usage exceeds 80 % on a single core, the snapshot is also saved.

Annealing Algorithm

To reduce performance overhead, the monitoring thread uses an annealing algorithm:

When a lag is detected, the main‑thread stack is first cached in memory instead of immediately writing a file.

The new stack is compared with the previous one:

If different, the snapshot is written to disk.

If identical, the check interval is increased following a Fibonacci sequence until the lag disappears or the stack changes.

This avoids writing duplicate files for the same lag and prevents endless snapshot writes when the main thread is deadlocked.

Time‑Consuming Stack Extraction

The snapshot taken at the moment of lag may not be the most time‑consuming stack. For example, the main thread may be drawing a small bubble while a larger bubble drawing operation actually caused the timeout.

Matrix stores recent main‑thread stacks in a circular buffer (size 3) and keeps the latest 20 stacks, sampled every 50 ms. This adds about 3 % CPU overhead, which is acceptable.

When a lag is detected, the system back‑traces the circular buffer to find the most time‑consuming stack using three heuristics: identical top‑function indicates identical stacks, repetition count approximates execution time, and the most recent stack among equally repeated ones is chosen.

Crash‑Lag Detection

Matrix also detects when an app is killed by the system (inspired by a Facebook blog). If a crash‑kill is identified, the last lag log before termination is marked as a “crash‑lag”.

Performance Data

When the time‑consuming stack extraction is disabled, the monitoring overhead is negligible. Enabling it adds about 3 % CPU usage due to the 50 ms sampling interval.

Conclusion

The iOS WeChat lag monitoring system, also applicable to macOS, helps locate unreasonable code and performance bottlenecks, improving app smoothness. Ongoing work includes adding power‑consumption stack capture and open‑sourcing the solution via Matrix.

Open‑Source Repository

Matrix repository: https://github.com/Tencent/matrix/tree/master/matrix/matrix-apple

Please give Matrix a star and feel free to submit issues or pull requests.