Repository navigation
feat(metrickit): Add flame graph attachments - #9347
Merged
Merged
Conversation
Contributor
|
7 of 9 tasks
Size Analysis1 component analyzed iOS Builds
|
📲 Install BuildsiOS
|
philprime
marked this pull request as ready for review
October 15, 2026 07:14
philprime
requested review from
NinjaLikesCheez,
itaybre and
noahsmartin
as code owners
October 15, 2026 07:14
7 of 9 tasks
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit dab630b. Configure here.
3 of 6 tasks
itaybre
approved these changes
Oct 21, 2026
itaybre
left a comment
Contributor
There was a problem hiding this comment.
LGTM, with a very small question
itaybre
enabled auto-merge (squash)
October 21, 2026 19:04
itaybre
added a commit
that referenced
this pull request
Oct 21, 2026
Resolve conflicts with the MetricKit flame graph attachments (#9347): pass the hang reporting mode and process start date to the manager, keep the integration init tests in their own file, and gate the enableMetricKit assignments in the new flame graph tests for V10.
itaybre
added a commit
that referenced
this pull request
Oct 21, 2026
Main added options.experimental.metrickit with hangReportingMode in #9347, which left this branch with a second MetricKit option object, options.experimental.metricKit. Add enabledDiagnosticReports to the existing SentryMetricKitOptions class and remove SentryMetricKit.Options so 9.31.0 ships a single experimental MetricKit option. Drop the v10 notes from the enableMetricKit docs, as requested in review, and regenerate the Swift API snapshots.
philprime
pushed a commit
that referenced
this pull request
Oct 22, 2026
The experimental hang reporting mode added in #9347 could only be set from Swift and ObjC code: - Options(dictionary:) had no key for it, so hybrid SDKs could not enable it. Add "metricKitHangReportingMode" accepting "legacy" or "flamegraphAttachment", ignoring unknown values. - SentryObjC.h did not import SentryObjCMetricKitOptions.h directly, which the SentryObjC maintainer doc requires. - SentryEnabledFeaturesBuilder did not report the mode, so events could not be filtered by it. Report "metricKitHangFlamegraphAttachment" when the mode is enabled.
itaybre
added a commit
that referenced
this pull request
Oct 27, 2026
* feat(metrickit): Add diagnostic report option The MetricKit integration always captured CPU, disk write and hang diagnostics, and crash diagnostics could not be enabled at all. Add options.experimental.metricKit.enabledDiagnosticReports to choose the captured reports. Before v10 a non-empty set opts in on its own and enableMetricKit keeps capturing the same three reports. In v10 the set defaults to those three, and an empty set disables the integration. Format the crash diagnostic exception value without Optional(...) wrappers, which crash reports would show once enabled. Fixes #8121 * feat(metrickit): Remove enableMetricKit in v10 In v10 the MetricKit integration is enabled by default, so the flag only duplicated what the experimental report set already expresses. Gate the option behind !SDK_V10 in Options, the dictionary initializer, SentryObjC and SentryObjCCompat, and let options.experimental.metricKit.enabledDiagnosticReports alone decide which reports the v10 integration captures. An empty set disables it. Drop the v10 API snapshot entries and move tests and test apps to the report set under SDK_V10. * docs(metrickit): Name v10 replacement for enableMetricKit Point the SentryObjC header note at options.experimental.metricKit.enabledDiagnosticReports so users know which option replaces the flag in v10. * ref(metrickit): Move DiagnosticReport helpers to their file Keep the exception type, mechanism and all-cases helpers next to the DiagnosticReport enum instead of in SentryMXManager. No behavior change. * test(metrickit): Split integration init tests The integration test file exceeds the 1000-line SwiftLint limit after main added the diagnostic metadata tests. Move the initializer and option tests, which only construct the integration, into their own test class. * Update changelog entry * ref(metrickit): Move report option to metrickit Main added options.experimental.metrickit with hangReportingMode in #9347, which left this branch with a second MetricKit option object, options.experimental.metricKit. Add enabledDiagnosticReports to the existing SentryMetricKitOptions class and remove SentryMetricKit.Options so 9.31.0 ships a single experimental MetricKit option. Drop the v10 notes from the enableMetricKit docs, as requested in review, and regenerate the Swift API snapshots. * docs(metrickit): Move changelog entry to Unreleased 9.31.0 was released while this branch was open, so the entry for the diagnostic report option belongs in the next version.
itaybre
added a commit
that referenced
this pull request
Oct 28, 2026
* feat(metrickit): Add diagnostic report option The MetricKit integration always captured CPU, disk write and hang diagnostics, and crash diagnostics could not be enabled at all. Add options.experimental.metricKit.enabledDiagnosticReports to choose the captured reports. Before v10 a non-empty set opts in on its own and enableMetricKit keeps capturing the same three reports. In v10 the set defaults to those three, and an empty set disables the integration. Format the crash diagnostic exception value without Optional(...) wrappers, which crash reports would show once enabled. Fixes #8121 * feat(metrickit): Remove enableMetricKit in v10 In v10 the MetricKit integration is enabled by default, so the flag only duplicated what the experimental report set already expresses. Gate the option behind !SDK_V10 in Options, the dictionary initializer, SentryObjC and SentryObjCCompat, and let options.experimental.metricKit.enabledDiagnosticReports alone decide which reports the v10 integration captures. An empty set disables it. Drop the v10 API snapshot entries and move tests and test apps to the report set under SDK_V10. * docs(metrickit): Name v10 replacement for enableMetricKit Point the SentryObjC header note at options.experimental.metricKit.enabledDiagnosticReports so users know which option replaces the flag in v10. * ref(metrickit): Move DiagnosticReport helpers to their file Keep the exception type, mechanism and all-cases helpers next to the DiagnosticReport enum instead of in SentryMXManager. No behavior change. * test(metrickit): Split integration init tests The integration test file exceeds the 1000-line SwiftLint limit after main added the diagnostic metadata tests. Move the initializer and option tests, which only construct the integration, into their own test class. * Update changelog entry * ref(metrickit): Move report option to metrickit Main added options.experimental.metrickit with hangReportingMode in #9347, which left this branch with a second MetricKit option object, options.experimental.metricKit. Add enabledDiagnosticReports to the existing SentryMetricKitOptions class and remove SentryMetricKit.Options so 9.31.0 ships a single experimental MetricKit option. Drop the v10 notes from the enableMetricKit docs, as requested in review, and regenerate the Swift API snapshots. * docs(metrickit): Move changelog entry to Unreleased 9.31.0 was released while this branch was open, so the entry for the diagnostic report option belongs in the next version. * ref(metrics): Add internal metric timestamp parameter The metrics API always stamps a metric with the current time, so SDK integrations cannot report a metric for a moment in the past. MetricKit metric payloads describe a reporting interval of up to a day before they are delivered. Add internal count, distribution and gauge overloads that take a timestamp. They are not part of the public SentryMetricsApiProtocol. The SDK sends the timestamp as is and leaves the accepted age to Relay, which rejects trace metrics older than the retention period. Fixes #9268 * feat(metrickit): Send metric payloads as metrics Add enabledMetricReports to the MetricKit options so MetricKit metric payloads can be sent as Sentry metrics named metrickit.<group>.<name>. The option defaults to an empty set, keeping metrics opt-in. Each metric is stamped at the middle of the payload interval and carries the app and OS versions the payload was recorded with. The release and OS version are applied through an internal override that runs after scope enrichment, so they are not replaced by the running app's values. Histograms are left for a follow-up. Fixes #9269 Refs COCOA-2027 * fix(metrickit): Exclude metric payloads on macOS MXMetricPayload is unavailable on macOS, so building the metric report code for macOS failed. Only compile it for iOS and visionOS and document that enabledMetricReports has no effect on macOS. * fix(metrickit): Send metric payloads on macOS 26 The Xcode 26 SDK makes MXMetricPayload available on macOS, and MetricKit delivers metric payloads there from macOS 26. Compile the metric report code for macOS when building with Xcode 26 or later, and keep excluding it for older SDKs that mark it unavailable. Also move the changelog entry after the one merged from main. * fix(metrickit): Drop session attrs from old metrics Metrics from a MetricKit payload only get the scope attributes that can't change between app runs and a trace ID per payload, like events from a previous process. The user, replay, custom scope attributes and running OS version are left out.
itaybre
added a commit
that referenced
this pull request
Oct 31, 2026
* feat(metrickit): Add diagnostic report option The MetricKit integration always captured CPU, disk write and hang diagnostics, and crash diagnostics could not be enabled at all. Add options.experimental.metricKit.enabledDiagnosticReports to choose the captured reports. Before v10 a non-empty set opts in on its own and enableMetricKit keeps capturing the same three reports. In v10 the set defaults to those three, and an empty set disables the integration. Format the crash diagnostic exception value without Optional(...) wrappers, which crash reports would show once enabled. Fixes #8121 * feat(metrickit): Remove enableMetricKit in v10 In v10 the MetricKit integration is enabled by default, so the flag only duplicated what the experimental report set already expresses. Gate the option behind !SDK_V10 in Options, the dictionary initializer, SentryObjC and SentryObjCCompat, and let options.experimental.metricKit.enabledDiagnosticReports alone decide which reports the v10 integration captures. An empty set disables it. Drop the v10 API snapshot entries and move tests and test apps to the report set under SDK_V10. * docs(metrickit): Name v10 replacement for enableMetricKit Point the SentryObjC header note at options.experimental.metricKit.enabledDiagnosticReports so users know which option replaces the flag in v10. * ref(metrickit): Move DiagnosticReport helpers to their file Keep the exception type, mechanism and all-cases helpers next to the DiagnosticReport enum instead of in SentryMXManager. No behavior change. * test(metrickit): Split integration init tests The integration test file exceeds the 1000-line SwiftLint limit after main added the diagnostic metadata tests. Move the initializer and option tests, which only construct the integration, into their own test class. * Update changelog entry * ref(metrickit): Move report option to metrickit Main added options.experimental.metrickit with hangReportingMode in #9347, which left this branch with a second MetricKit option object, options.experimental.metricKit. Add enabledDiagnosticReports to the existing SentryMetricKitOptions class and remove SentryMetricKit.Options so 9.31.0 ships a single experimental MetricKit option. Drop the v10 notes from the enableMetricKit docs, as requested in review, and regenerate the Swift API snapshots. * docs(metrickit): Move changelog entry to Unreleased 9.31.0 was released while this branch was open, so the entry for the diagnostic report option belongs in the next version. * ref(metrics): Add internal metric timestamp parameter The metrics API always stamps a metric with the current time, so SDK integrations cannot report a metric for a moment in the past. MetricKit metric payloads describe a reporting interval of up to a day before they are delivered. Add internal count, distribution and gauge overloads that take a timestamp. They are not part of the public SentryMetricsApiProtocol. The SDK sends the timestamp as is and leaves the accepted age to Relay, which rejects trace metrics older than the retention period. Fixes #9268 * feat(metrickit): Send metric payloads as metrics Add enabledMetricReports to the MetricKit options so MetricKit metric payloads can be sent as Sentry metrics named metrickit.<group>.<name>. The option defaults to an empty set, keeping metrics opt-in. Each metric is stamped at the middle of the payload interval and carries the app and OS versions the payload was recorded with. The release and OS version are applied through an internal override that runs after scope enrichment, so they are not replaced by the running app's values. Histograms are left for a follow-up. Fixes #9269 Refs COCOA-2027 * feat(metrickit): Receive diagnostics from MetricManager On iOS, macOS and visionOS 27, read MetricKit diagnostics from MetricManager. Earlier versions keep the MXMetricManager subscriber. The subscriber stays registered for metric payloads but ignores its diagnostic payloads while MetricManager delivers them, so a diagnostic is never captured twice. Both APIs convert their diagnostics to SentryMXDiagnostic, which goes through the same filtering, event building, metadata and call stack handling, so a diagnostic produces the same event on either API. Add the memoryException diagnostic report for iOS 27, including its ObjC option and options dictionary name. It isn't enabled by default because watchdog termination tracking already reports out-of-memory terminations. Fixes #9276 Fixes COCOA-2034 * ref(metrickit): Move memory exceptions to a separate PR Memory exception diagnostics are a separate feature with their own duplicate trade-off against watchdog terminations, so they get their own pull request stacked on this one. * fix(metrickit): Exclude metric payloads on macOS MXMetricPayload is unavailable on macOS, so building the metric report code for macOS failed. Only compile it for iOS and visionOS and document that enabledMetricReports has no effect on macOS. * fix(metrickit): Send metric payloads on macOS 26 The Xcode 26 SDK makes MXMetricPayload available on macOS, and MetricKit delivers metric payloads there from macOS 26. Compile the metric report code for macOS when building with Xcode 26 or later, and keep excluding it for older SDKs that mark it unavailable. Also move the changelog entry after the one merged from main. * feat(metrickit): Receive metrics from MetricManager On iOS and macOS 27, read MetricKit metrics from MetricManager's metric reports, using the same manager as diagnostics. The MXMetricManager subscriber ignores metric payloads while MetricManager delivers them, so a metric is never sent twice. visionOS keeps the legacy payloads because MetricManager doesn't report metrics there. Each MetricResult is sent with the same name, type and unit as its legacy counterpart, sharing the timestamp and version attributes. Add opt-in reports for the values only MetricManager provides: the total hitch and animation time and the Metal frame rate, frame count and active drawing duration with the layer name as an attribute. Fixes #9280 Fixes COCOA-2038 * ref(metrickit): Split MetricKit receivers Split the MetricKit handling into one receiver per API, one processor per diagnostic type and a shared capturer, so SentryMXManager doesn't keep growing with every new MetricKit API. SentryMetricManager receives the xOS 27 MetricManager diagnostics and SentryMXManager only the legacy subscriber payloads. The integration decides which one delivers diagnostics, and both convert them through the same processors and capture them with SentryMXDiagnosticCapturer, so they keep producing the same events. * feat(metrickit): Capture memory exception diagnostics (#9465) Add the memoryException diagnostic report for MetricManager's memory exception diagnostics on iOS 27. Each one becomes an unhandled error with the stack of the thread MetricKit attributes the termination to. It isn't enabled by default because watchdog termination tracking already reports out-of-memory terminations. The report is available from Swift, ObjC and the options dictionary, and the sample app enables it to compare both. Refs #9276 Refs COCOA-2034 * test: Disable default diagnostics in V10 test V10 enables diagnostic reports by default, so the metrics-only test still created a diagnostic capturer. * docs: Explain MetricManager compiler check * feat(metrickit): Add new reports to ObjC and dicts main added the SentryObjCMetricKitMetricReport bitmask and the metrickit options dictionary key, which didn't know the five metric reports this branch adds. Append them as bits 47 to 51 and accept their names in the options dictionary.
itaybre
added a commit
that referenced
this pull request
Nov 13, 2026
* feat(metrickit): Add diagnostic report option The MetricKit integration always captured CPU, disk write and hang diagnostics, and crash diagnostics could not be enabled at all. Add options.experimental.metricKit.enabledDiagnosticReports to choose the captured reports. Before v10 a non-empty set opts in on its own and enableMetricKit keeps capturing the same three reports. In v10 the set defaults to those three, and an empty set disables the integration. Format the crash diagnostic exception value without Optional(...) wrappers, which crash reports would show once enabled. Fixes #8121 * feat(metrickit): Remove enableMetricKit in v10 In v10 the MetricKit integration is enabled by default, so the flag only duplicated what the experimental report set already expresses. Gate the option behind !SDK_V10 in Options, the dictionary initializer, SentryObjC and SentryObjCCompat, and let options.experimental.metricKit.enabledDiagnosticReports alone decide which reports the v10 integration captures. An empty set disables it. Drop the v10 API snapshot entries and move tests and test apps to the report set under SDK_V10. * docs(metrickit): Name v10 replacement for enableMetricKit Point the SentryObjC header note at options.experimental.metricKit.enabledDiagnosticReports so users know which option replaces the flag in v10. * ref(metrickit): Move DiagnosticReport helpers to their file Keep the exception type, mechanism and all-cases helpers next to the DiagnosticReport enum instead of in SentryMXManager. No behavior change. * test(metrickit): Split integration init tests The integration test file exceeds the 1000-line SwiftLint limit after main added the diagnostic metadata tests. Move the initializer and option tests, which only construct the integration, into their own test class. * Update changelog entry * ref(metrickit): Move report option to metrickit Main added options.experimental.metrickit with hangReportingMode in #9347, which left this branch with a second MetricKit option object, options.experimental.metricKit. Add enabledDiagnosticReports to the existing SentryMetricKitOptions class and remove SentryMetricKit.Options so 9.31.0 ships a single experimental MetricKit option. Drop the v10 notes from the enableMetricKit docs, as requested in review, and regenerate the Swift API snapshots. * docs(metrickit): Move changelog entry to Unreleased 9.31.0 was released while this branch was open, so the entry for the diagnostic report option belongs in the next version. * ref(metrics): Add internal metric timestamp parameter The metrics API always stamps a metric with the current time, so SDK integrations cannot report a metric for a moment in the past. MetricKit metric payloads describe a reporting interval of up to a day before they are delivered. Add internal count, distribution and gauge overloads that take a timestamp. They are not part of the public SentryMetricsApiProtocol. The SDK sends the timestamp as is and leaves the accepted age to Relay, which rejects trace metrics older than the retention period. Fixes #9268 * feat(metrickit): Send metric payloads as metrics Add enabledMetricReports to the MetricKit options so MetricKit metric payloads can be sent as Sentry metrics named metrickit.<group>.<name>. The option defaults to an empty set, keeping metrics opt-in. Each metric is stamped at the middle of the payload interval and carries the app and OS versions the payload was recorded with. The release and OS version are applied through an internal override that runs after scope enrichment, so they are not replaced by the running app's values. Histograms are left for a follow-up. Fixes #9269 Refs COCOA-2027 * feat(metrickit): Receive diagnostics from MetricManager On iOS, macOS and visionOS 27, read MetricKit diagnostics from MetricManager. Earlier versions keep the MXMetricManager subscriber. The subscriber stays registered for metric payloads but ignores its diagnostic payloads while MetricManager delivers them, so a diagnostic is never captured twice. Both APIs convert their diagnostics to SentryMXDiagnostic, which goes through the same filtering, event building, metadata and call stack handling, so a diagnostic produces the same event on either API. Add the memoryException diagnostic report for iOS 27, including its ObjC option and options dictionary name. It isn't enabled by default because watchdog termination tracking already reports out-of-memory terminations. Fixes #9276 Fixes COCOA-2034 * ref(metrickit): Move memory exceptions to a separate PR Memory exception diagnostics are a separate feature with their own duplicate trade-off against watchdog terminations, so they get their own pull request stacked on this one. * fix(metrickit): Exclude metric payloads on macOS MXMetricPayload is unavailable on macOS, so building the metric report code for macOS failed. Only compile it for iOS and visionOS and document that enabledMetricReports has no effect on macOS. * fix(metrickit): Send metric payloads on macOS 26 The Xcode 26 SDK makes MXMetricPayload available on macOS, and MetricKit delivers metric payloads there from macOS 26. Compile the metric report code for macOS when building with Xcode 26 or later, and keep excluding it for older SDKs that mark it unavailable. Also move the changelog entry after the one merged from main. * feat(metrickit): Receive metrics from MetricManager On iOS and macOS 27, read MetricKit metrics from MetricManager's metric reports, using the same manager as diagnostics. The MXMetricManager subscriber ignores metric payloads while MetricManager delivers them, so a metric is never sent twice. visionOS keeps the legacy payloads because MetricManager doesn't report metrics there. Each MetricResult is sent with the same name, type and unit as its legacy counterpart, sharing the timestamp and version attributes. Add opt-in reports for the values only MetricManager provides: the total hitch and animation time and the Metal frame rate, frame count and active drawing duration with the layer name as an attribute. Fixes #9280 Fixes COCOA-2038 * ref(metrickit): Split MetricKit receivers Split the MetricKit handling into one receiver per API, one processor per diagnostic type and a shared capturer, so SentryMXManager doesn't keep growing with every new MetricKit API. SentryMetricManager receives the xOS 27 MetricManager diagnostics and SentryMXManager only the legacy subscriber payloads. The integration decides which one delivers diagnostics, and both convert them through the same processors and capture them with SentryMXDiagnosticCapturer, so they keep producing the same events. * feat(metrickit): Send MetricKit histograms Map the launch, hang time and cellular condition histograms of both MetricKit APIs to distribution metrics with one value per sample at the middle of its bucket, spread across the reporting interval and capped at about 100 values per histogram. Fixes COCOA-2033 * ref(metrickit): Split MetricReport dictionary init Move init?(dictionaryValue:) into its own file so the MetricReport file stays within SwiftLint's file length limit, instead of disabling the rule. * fix(metrickit): Keep rare histogram buckets Scaling a histogram above the value limit rounded every bucket on its own, so a bucket whose share rounded to zero was dropped. This lost rare long hangs, and a histogram of many small buckets sent nothing at all. Every non-empty bucket now sends at least one value. The total can exceed the limit by up to one value per bucket. * Apply suggestion from @itaybre * Update changelog
philprime
added a commit
to getsentry/sentry-docs
that referenced
this pull request
Nov 17, 2026
## DESCRIBE YOUR PR Expand the MetricKit documentation to explain system-provided hang diagnostics, how to interpret sampled flame graphs, and the limits of default reporting. Include Swift and SentryObjC configuration for experimental flame graph attachments, with attachment quota, symbolication, fallback, and raw payload guidance. This is an early draft tied to the implementation PRs below. Legacy reporting remains the default. The draft distinguishes aggregate samples from time-based profiles and does not promise culprit identification or improved grouping, which these implementations do not provide. Release availability and final limits need review before publication. Related implementation PRs: - getsentry/sentry-cocoa#9347 - getsentry/relay#6473 - getsentry/sentry#126459 - getsentry/sentry#126461 ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST - [x] Checked Vercel preview for correctness, including links - [x] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs)
6 of 11 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

📜 Description
Add experimental MetricKit hang reporting through
options.experimental.metrickit.hangReportingMode = .flamegraphAttachment, also available throughSentryObjC.Send a versioned
flamegraph.jsonattachment with aggregated call trees, captured addresses, sample counts, and diagnostic debug metadata in the event's envelope. Native SwiftEncodablemodels underSentryRelayWireFormatfollow the flame graph attachment specification. Inconsistent sample counts and attachments exceeding 10 MiB are rejected. The default.legacymode reports the flattened call stack tree.💡 Motivation and Context
Flame graph attachments preserve MetricKit hang samples and symbolication inputs for server-side processing and culprit identification in Relay.
Blocked by getsentry/relay#6473. Relay support must land before this PR can merge.💚 How did you test it?
flamegraph.jsonstored asevent.flamegraphand the rawMXDiagnosticPayload.jsonattachment, with no processing errors: https://sentry-sdks.sentry.io/issues/7738016221/events/8b04e1bf48504280842443da5575c9fb/make formatandmake analyzepassed.📝 Checklist
You have to check all boxes before merging:
sendDefaultPIIis enabled.Closes #9352