Skip to content

feat(metrickit): Add flame graph attachments - #9347

Merged
itaybre merged 12 commits into
mainfrom
philprime/metrickit/flamegraph-attachment
Oct 21, 2026
Merged

itaybre merged 12 commits into
mainfrom
philprime/metrickit/flamegraph-attachment

Conversation

@philprime

@philprime philprime commented Oct 14, 2026 •

Copy link
Copy Markdown
Member

📜 Description

Add experimental MetricKit hang reporting through options.experimental.metrickit.hangReportingMode = .flamegraphAttachment, also available through SentryObjC.

Send a versioned flamegraph.json attachment with aggregated call trees, captured addresses, sample counts, and diagnostic debug metadata in the event's envelope. Native Swift Encodable models under SentryRelayWireFormat follow the flame graph attachment specification. Inconsistent sample counts and attachments exceeding 10 MiB are rejected. The default .legacy mode 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?

  • Verified a real iOS-Swift MetricKit hang event with flamegraph.json stored as event.flamegraph and the raw MXDiagnosticPayload.json attachment, with no processing errors: https://sentry-sdks.sentry.io/issues/7738016221/events/8b04e1bf48504280842443da5575c9fb/
  • make format and make analyze passed.
  • iOS and macOS builds passed.
  • 55 targeted iOS MetricKit and wire-format tests passed, covering attachment headers, tree preservation, frame deduplication, sample-count validation, exact JSON encoding, optional-field omission, and integer preservation.
  • Earlier targeted Objective-C option tests passed, with three existing skips.
  • The full iOS suite was started but interrupted, so it is not reported as passing.
  • Regenerated the Swift and Objective-C public API snapshots.

📝 Checklist

You have to check all boxes before merging:

  • I added tests to verify the changes.
  • No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
  • I updated the docs if needed.
  • I updated the wizard if needed.
  • Review from the native team if needed.
  • No breaking change or entry added to the changelog.
  • No breaking change for hybrid SDKs or communicated to hybrid SDKs.
  • Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.
  • If I added a new public API, I also added it to the SentryObjC wrapper.

Closes #9352

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor
Messages
📖 Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against a427411

@philprime philprime changed the title feat: Add MetricKit flame graph attachments feat(metrickit): Add flame graph attachments Oct 14, 2026
@philprime philprime self-assigned this Oct 14, 2026
@philprime philprime added the run-full-ci Allows gated GitHub Action workflows to run for a labelled pull request label Oct 14, 2026
@sentry

sentry Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

Size Analysis

1 component analyzed

iOS Builds

Name Configuration Version Download Size Install Size
SDK-Size (iOS)
io.sentry.sample.SDK-Size
Release 9.30.2 (1) 1.2 MB (+14.2 KB) 3.1 MB (+32.8 KB)

Configure sentry-cocoa status check rules

@sentry

sentry Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

📲 Install Builds

iOS

🔗 App Name App ID Version Configuration
SDK-Size io.sentry.sample.SDK-Size 9.30.2 (1) Release

⚙️ sentry-cocoa Build Distribution Settings

@philprime
philprime marked this pull request as ready for review October 15, 2026 07:14
@philprime
philprime requested a review from a team October 15, 2026 07:14

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ 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.

@linear-code

linear-code Bot commented Oct 16, 2026

Copy link
Copy Markdown

COCOA-2064

@philprime philprime removed the Blocked label Oct 21, 2026

@itaybre itaybre left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, with a very small question

@itaybre
itaybre enabled auto-merge (squash) October 21, 2026 19:04
@github-actions github-actions Bot removed the approved label Oct 21, 2026
@itaybre
itaybre merged commit 9b375db into main Oct 21, 2026
311 of 313 checks passed
@itaybre
itaybre deleted the philprime/metrickit/flamegraph-attachment branch October 21, 2026 19:05
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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

run-full-ci Allows gated GitHub Action workflows to run for a labelled pull request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(metrickit): Add flame graph attachments

2 participants