feat: Use full flamegraph for metrickit app hangs (#7185)

* feat: Use full flamegraph for metrickit app hangs

* PR feedback

Author: noahsmartin

CHANGELOG.md

@@ -7,6 +7,7 @@
 - Add package traits for UI framework opt-out (#7578).
   When building from source with Swift 6.1+ (using `Package@swift-6.1.swift`), you can enable the `NoUIFramework` trait to avoid linking UIKit or AppKit. Use this for command-line tools, headless server contexts, or other environments where UI frameworks are unavailable.
   In Xcode 26.4 and later, add the Sentry package as a dependency and the `SentrySPM` product, then enable the `NoUIFramework` trait on the package reference (Package Dependencies → select Sentry → Traits).
+  - Metric kit app hangs now report a full flamegraph rather than just one stacktrace during the hang. (#7185)
 
 ### Fixes
 

Sources/Sentry/Public/SentryFrame.h

@@ -70,6 +70,16 @@ NS_SWIFT_NAME(Frame)
  */
 @property (nonatomic, copy) NSString *_Nullable contextLine;
 
+/**
+ * Index of the parent frame used for flamegraphs.
+ */
+@property (nonatomic, copy) NSNumber *_Nullable parentIndex;
+
+/**
+ * Number of samples recorded that contained this frame, used for flamegraphs.
+ */
+@property (nonatomic, copy) NSNumber *_Nullable sampleCount;
+
 /**
  * Source code lines before the error location (up to 5 lines).
  * Mostly used for Godot errors.

Sources/Sentry/SentryFrame.m

@@ -28,6 +28,8 @@ - (instancetype)init
     [serializedData setValue:self.platform forKey:@"platform"];
     [serializedData setValue:self.contextLine forKey:@"context_line"];
     [serializedData setValue:self.preContext forKey:@"pre_context"];
+    [serializedData setValue:self.parentIndex forKey:@"parent_index"];
+    [serializedData setValue:self.sampleCount forKey:@"sample_count"];
     [serializedData setValue:self.postContext forKey:@"post_context"];
     [serializedData setValue:sentry_sanitize(self.vars) forKey:@"vars"];
     [SentryDictionary setBoolValue:self.inApp forKey:@"in_app" intoDictionary:serializedData];

Sources/Swift/Core/MetricKit/SentryMXCallStackTree+Parsing.swift

@@ -8,22 +8,7 @@ extension SentryMXCallStackTree {
             frame.toDebugMeta()
         }.unique { $0.debugID }
     }
-    
-    func prepare(event: Event, inAppLogic: SentryInAppLogic?, handled: Bool) {
-        let debugMeta = toDebugMeta()
-        let threads = sentryMXBacktrace(inAppLogic: inAppLogic, handled: handled)
-        // First look for the crashing thread, but for events that were not a crash (like a hang) take the first thread
-        // since those events only report one thread
-        let exceptionThread = threads.first { $0.crashed?.boolValue == true } ?? threads.first
-        event.debugMeta = debugMeta
-        event.threads = threads
-        
-        if let exceptionThread, let exception = event.exceptions?[0] {
-            exception.stacktrace = exceptionThread.stacktrace
-            exception.threadId = exceptionThread.threadId
-        }
-    }
-    
+
     // A MetricKit CallStackTree is a flamegraph, but many Sentry APIs only support
     // a thread backtrace. A flamegraph is just a collection of many thread backtraces
     // generated by taking multiple samples. For example a hang from metric kit will
@@ -35,8 +20,6 @@ extension SentryMXCallStackTree {
     // it represents data that is sampled across many threads and aggregated, we do not
     // know which samples came from which thread. Instead we create just one fake thread
     // that just contains the most common callstack.
-    //
-    // We hope to add flamegraph support at some point and that is tracked here: https://github.com/getsentry/sentry-cocoa/issues/7062
     func sentryMXBacktrace(inAppLogic: SentryInAppLogic?, handled: Bool) -> [SentryThread] {
         callStacks.enumerated().map { index, callStack in
             let thread = SentryThread(threadId: NSNumber(value: index))
@@ -66,6 +49,44 @@ extension SentryMXCallStackTree {
             return thread
         }
     }
+
+    /// Flattens the call stack tree into a single thread with all frames.
+    /// Each frame includes metadata to allow reconstructing the original tree:
+    /// - `parent_frame_index`: The index of the parent frame in the flat list (-1 for root frames)
+    /// - `sample_count`: The number of samples at this frame
+    ///
+    /// This preserves all sample data from the flamegraph rather than just the most common stack.
+    func flattenedBacktrace(inAppLogic: SentryInAppLogic?, handled: Bool) -> [SentryThread] {
+        callStacks.enumerated().map { index, callStack in
+            let thread = SentryThread(threadId: NSNumber(value: index))
+            var frames: [Frame] = []
+
+            // Traverse the tree and flatten all frames with parent references
+            for rootFrame in callStack.callStackRootFrames {
+                flattenFrame(rootFrame, parentIndex: -1, frames: &frames, inAppLogic: inAppLogic)
+            }
+
+            thread.stacktrace = SentryStacktrace(frames: frames, registers: [:])
+            thread.crashed = NSNumber(value: (callStack.threadAttributed ?? false) && !handled)
+            return thread
+        }
+    }
+
+    private func flattenFrame(_ mxFrame: SentryMXFrame, parentIndex: Int, frames: inout [Frame], inAppLogic: SentryInAppLogic?) {
+        let currentIndex = frames.count
+        let frame = mxFrame.toSentryFrameWithTreeData(parentFrameIndex: parentIndex)
+        if let package = frame.package {
+            frame.inApp = NSNumber(value: inAppLogic?.is(inApp: package) ?? false)
+        } else {
+            frame.inApp = true
+        }
+        frames.append(frame)
+
+        // Recursively process child frames
+        for subFrame in mxFrame.subFrames ?? [] {
+            flattenFrame(subFrame, parentIndex: currentIndex, frames: &frames, inAppLogic: inAppLogic)
+        }
+    }
 }
 
 extension SentryMXCallStack {
@@ -87,7 +108,7 @@ extension SentryMXFrame {
         }
         return [result] + (subFrames?.flatMap { $0.toDebugMeta() } ?? [])
     }
-    
+
     func toSamples() -> [MXSample] {
         let selfFrame = MXSample.MXFrame(binaryUUID: binaryUUID, offsetIntoBinaryTextSegment: offsetIntoBinaryTextSegment, binaryName: binaryName, address: address)
         let subframes = subFrames ?? []
@@ -100,6 +121,21 @@ extension SentryMXFrame {
         }
         return result
     }
+
+    /// Converts this frame to a SentryFrame.
+    func toSentryFrameWithTreeData(parentFrameIndex: Int) -> Frame {
+        let frame = Frame()
+        frame.package = binaryName
+        frame.instructionAddress = sentry_formatHexAddressUInt64Swift(address)
+        if offsetIntoBinaryTextSegment >= 0 && offsetIntoBinaryTextSegment < address {
+            frame.imageAddress = sentry_formatHexAddressUInt64Swift(address - UInt64(offsetIntoBinaryTextSegment))
+        }
+
+        frame.parentIndex = parentFrameIndex as NSNumber
+        frame.sampleCount = sampleCount as NSNumber?
+
+        return frame
+    }
 }
 
 private extension MXSample.MXFrame {

Sources/Swift/Core/MetricKit/SentryMXManager.swift

@@ -80,12 +80,12 @@ final class SentryMXManager: NSObject, MXMetricManagerSubscriber {
             payload.hangDiagnostics?.forEach { diagnostic in
                 let hangDuration = measurementFormatter.string(from: diagnostic.hangDuration)
                 let exceptionValue = "MXHangDiagnostic hangDuration:\(hangDuration)"
-                captureEvent(handled: true, exceptionValue: exceptionValue, exceptionType: "MXHangDiagnostic", exceptionMechanism: hangDiagnosticMechanism, timeStampBegin: payload.timeStampBegin, diagnostic: diagnostic)
+                captureEvent(handled: true, exceptionValue: exceptionValue, exceptionType: "MXHangDiagnostic", exceptionMechanism: hangDiagnosticMechanism, timeStampBegin: payload.timeStampBegin, diagnostic: diagnostic, useFullCallStackTree: true)
             }
         }
     }
 
-    func captureEvent(handled: Bool, exceptionValue: String, exceptionType: String, exceptionMechanism: String, timeStampBegin: Date, diagnostic: MXDiagnostic & CallStackTreeProviding) {
+    func captureEvent(handled: Bool, exceptionValue: String, exceptionType: String, exceptionMechanism: String, timeStampBegin: Date, diagnostic: MXDiagnostic & CallStackTreeProviding, useFullCallStackTree: Bool = false) {
         if let callStackTree = try? SentryMXCallStackTree.from(data: diagnostic.callStackTree.jsonRepresentation()) {
             let event = Event(level: handled ? .warning : .error)
             event.timestamp = timeStampBegin
@@ -95,12 +95,29 @@ final class SentryMXManager: NSObject, MXMetricManagerSubscriber {
             mechanism.synthetic = true
             exception.mechanism = mechanism
             event.exceptions = [exception]
-            capture(event: event, handled: handled, callStackTree: callStackTree, diagnosticJSON: diagnostic.jsonRepresentation())
+            capture(event: event, handled: handled, callStackTree: callStackTree, diagnosticJSON: diagnostic.jsonRepresentation(), useFullCallStackTree: useFullCallStackTree)
         }
     }
 
-    func capture(event: Event, handled: Bool, callStackTree: SentryMXCallStackTree, diagnosticJSON: Data) {
-        callStackTree.prepare(event: event, inAppLogic: inAppLogic, handled: handled)
+    func capture(event: Event, handled: Bool, callStackTree: SentryMXCallStackTree, diagnosticJSON: Data, useFullCallStackTree: Bool = false) {
+        let debugMeta = callStackTree.toDebugMeta()
+        let threads: [SentryThread]
+        if useFullCallStackTree {
+            // For hang diagnostics, use the flattened tree to preserve all samples
+            threads = callStackTree.flattenedBacktrace(inAppLogic: inAppLogic, handled: handled)
+        } else {
+            threads = callStackTree.sentryMXBacktrace(inAppLogic: inAppLogic, handled: handled)
+        }
+        // First look for the crashing thread, but for events that were not a crash (like a hang) take the first thread
+        // since those events only report one thread
+        let exceptionThread = threads.first { $0.crashed?.boolValue == true } ?? threads.first
+        event.debugMeta = debugMeta
+        event.threads = threads
+
+        if let exceptionThread, let exception = event.exceptions?[0] {
+            exception.stacktrace = exceptionThread.stacktrace
+            exception.threadId = exceptionThread.threadId
+        }
         // The crash event can be way from the past. We don't want to impact the current session.
         // Therefore we don't call captureFatalEvent.
         capture(event: event, diagnosticJSON: diagnosticJSON)

Tests/SentryTests/Integrations/MetricKit/SentryMXCallStackTreeTests.swift

@@ -60,6 +60,17 @@ final class SentryMXCallStackTreeTests: XCTestCase {
         XCTAssertEqual(true, frames[0].inApp?.boolValue)
     }
 
+    func testInAppTrue_WhenPackageIsNilFlamegraph() throws {
+        let contents = try contentsOfResource("MetricKitCallstacks/per-thread-nil-package")
+        let callStackTree = try SentryMXCallStackTree.from(data: contents)
+        let threads = callStackTree.flattenedBacktrace(inAppLogic: nil, handled: false)
+        XCTAssertEqual(1, threads.count)
+        let frames = try XCTUnwrap(threads[0].stacktrace).frames
+        XCTAssertEqual(1, frames.count)
+        XCTAssertNil(frames[0].package)
+        XCTAssertEqual(true, frames[0].inApp?.boolValue)
+    }
+
     func testDecodeCallStackTree_UnknownFieldsPayload() throws {
         let contents = try contentsOfResource("MetricKitCallstacks/tree-unknown-fields")
         let callStackTree = try SentryMXCallStackTree.from(data: contents)