Analyze potential hangs from a .trace bundle
analyzeHangsAnalyze .trace files for hangs: export potential-hangs schema, aggregate stats (counts, durations), and return top N longest hangs with main thread violation classification.
Instructions
[mg.trace] Run xcrun xctrace export against a .trace bundle for the potential-hangs schema and return aggregated stats (Hang vs Microhang counts, longest, average, total duration) plus the top N longest hangs sorted by duration. Use minDurationMs: 250 to filter to user-visible hangs only. Pass topFramesByHangStartNs: { '<startNs>': '<topFrame>' } to enrich each top hang with a mainThreadViolations[] field that classifies the kind of work blocking the main thread (sync-io, db-lock, network, lock-contention). The map keys are stringified startNs values; the typical pipeline is to call analyzeTimeProfile separately on the same trace, correlate samples to the hang windows by timestamp, then re-call analyzeHangs with the resulting map.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tracePath | Yes | Absolute path to a `.trace` bundle (output of `xctrace record` with the Time Profiler or Hangs template). | |
| topN | No | Return the top N longest hangs in the response (default 10). | |
| minDurationMs | No | Filter out hangs shorter than this duration in milliseconds (default 0, include all). Use 250 to focus on 'real' hangs only. | |
| timeRangeMs | No | Optional time-window filter. Only hangs whose `startNs` falls within `[startMs, endMs]` (milliseconds since recording start) are included. Use this to answer 'what hangs happened between t=2s and t=7s?' without re-recording. | |
| topFramesByHangStartNs | No | Optional supplemental map from a hang's `startNs` (as a string) to the top frame seen during that hang. When provided, each matching hang in `top[]` is enriched with `mainThreadViolations[]` that catalog the kind of work happening on the main thread (sync-io, db-lock, network, lock-contention). Typical pipeline: call `analyzeTimeProfile` separately on the same `.trace`, correlate samples to hang windows by timestamp, then re-call `analyzeHangs` with the resulting map. Omit to skip the enrichment. SUPERSEDED in v1.12 by `includeStackClassification: true`, which builds this map internally. | |
| includeStackClassification | No | v1.12+. When true, analyzeHangs internally exports the `time-profile` schema in parallel with `potential-hangs`, correlates samples to hang windows by timestamp, picks the dominant top frame per hang, and runs `classifyHangFrame` on it. The `mainThreadViolations[]` field on each top hang is populated automatically. Replaces the v1.9 caller-built `topFramesByHangStartNs` map: most callers should set this flag instead of building the map manually. Adds a second xctrace export call, run in parallel with the hangs export so wall-clock is unchanged when the trace export succeeds. Falls back gracefully (empty violations, no error) when the time-profile schema is absent or xctrace SIGSEGVs on it. | |
| outputFormat | No | Response format. Omitted or `json` (default, preserves v1.8 behavior) returns JSON.stringify of the result. `markdown` renders a human-readable view of the same data. `both` returns both content items in one response, so a client can display markdown to the user and parse JSON for the agent loop without a second call. `verify-fix-table` (v1.10, applies to `analyzeAbandonedMemory` and `diffMemgraphs`) emits a focused 4-column markdown comparison table (Class | Before | After | Delta) of the actionable rows; other tools fall back to `markdown` for this value. |