---
title: "MetricKit"
description: "Capture MetricKit diagnostics and investigate app hangs with symbolicated flame graph attachments."
url: https://docs.sentry.io/platforms/apple/guides/visionos/configuration/metric-kit/
---

# MetricKit for visionOS

The [MetricKit](https://developer.apple.com/documentation/metrickit) integration subscribes to [MXHangDiagnostic](https://developer.apple.com/documentation/metrickit/mxhangdiagnostic), [MXDiskWriteExceptionDiagnostic](https://developer.apple.com/documentation/metrickit/mxdiskwriteexceptiondiagnostic) and [MXCPUExceptionDiagnostic](https://developer.apple.com/documentation/metrickit/mxcpuexceptiondiagnostic), which it converts to Sentry events.

This integration is available in SDK version 8.14.0 and later on iOS 15 and later and macOS 12 and later.

MetricKit controls the stack traces included in each diagnostic. Some contain only a few frames. To discard reports that aren't useful to you, filter them in [`beforeSend`](https://docs.sentry.io/platforms/apple/guides/visionos/configuration/filtering.md#filtering-error-events).

Identify MetricKit events by their `mechanism.type`: `mx_hang_diagnostic`, `mx_cpu_exception`, or `mx_disk_write_exception`.

## [Enable MetricKit](https://docs.sentry.io/platforms/apple/guides/visionos/configuration/metric-kit.md#enable-metrickit)

Enable this feature by setting the `enableMetricKit` option to `true`:

**Swift**

```swift
import Sentry

SentrySDK.start { options in
    options.dsn = "https://<key>@o<orgId>.ingest.sentry.io/<projectId>"
    options.enableMetricKit = true
}
```

**Objective-C**

```objc
@import Sentry;

[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.dsn = @"https://<key>@o<orgId>.ingest.sentry.io/<projectId>";
    options.enableMetricKit = YES;
}];
```

**Objective-C (SentryObjC)**

```objc
#import <SentryObjC/SentryObjC.h>

[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
    options.dsn = @"https://<key>@o<orgId>.ingest.sentry.io/<projectId>";
    options.enableMetricKit = YES;
}];
```

## [Hang Diagnostics](https://docs.sentry.io/platforms/apple/guides/visionos/configuration/metric-kit.md#hang-diagnostics)

MetricKit reports periods when your app is unresponsive. Each hang diagnostic includes a hang duration and a sampled call stack tree, which can contain multiple execution paths rather than a single stack trace. Apple controls which hangs are reported and how much detail they contain, so not every hang produces a diagnostic.

We recommend MetricKit for system-provided hang diagnostics. Disabling or pausing [App Hang tracking](https://docs.sentry.io/platforms/apple/guides/visionos/configuration/app-hangs.md) does not stop MetricKit reports, and `appHangTimeoutInterval` does not change MetricKit's detection threshold.

### [Enable Flame Graph Attachments](https://docs.sentry.io/platforms/apple/guides/visionos/configuration/metric-kit.md#enable-flame-graph-attachments)

By default, the SDK stores the sampled call tree in the event's stack trace. Large trees are subject to stack trace limits, which can leave the flame graph incomplete. Starting with SDK version 9.31.0, send the tree as a separate attachment to preserve it independently of those limits.

Flame graph attachment reporting is available for public testing. The configuration option is experimental and may change in a future release.

Set `hangReportingMode` to `.flamegraphAttachment` when configuring the SDK. This option affects hang diagnostics only:

**Swift**

```swift
import Sentry

SentrySDK.start { options in
    options.dsn = "https://<key>@o<orgId>.ingest.sentry.io/<projectId>"
    options.enableMetricKit = true
    options.experimental.metrickit.hangReportingMode = .flamegraphAttachment
}
```

**Objective-C (SentryObjC)**

```objc
#import <SentryObjC/SentryObjC.h>

[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
    options.dsn = @"https://<key>@o<orgId>.ingest.sentry.io/<projectId>";
    options.enableMetricKit = YES;
    options.experimental.metrickit.hangReportingMode =
        SentryObjCMetricKitHangReportingModeFlamegraphAttachment;
}];
```

The SDK sends a `flamegraph.json` attachment with each hang event. Upload your app's [debug information files](https://docs.sentry.io/platforms/apple/guides/visionos/dsym.md) so Sentry can symbolicate the flame graph using the same debug symbols as error events. Profiling does not need to be enabled.

To capture only hang diagnostics with MetricKit in Swift, replace `options.enableMetricKit = true` with `options.experimental.metrickit.enabledDiagnosticReports = [.hang]`. This requires SDK version 9.32.0 or later.

To return to default reporting, set `hangReportingMode` to `.legacy` (`SentryObjCMetricKitHangReportingModeLegacy` in Objective-C).

### [Investigate a Hang](https://docs.sentry.io/platforms/apple/guides/visionos/configuration/metric-kit.md#investigate-a-hang)

Open a MetricKit hang event in Sentry to view its stack trace and flame graph. Sentry selects a representative stack trace from the sampled call trees for issue grouping, considering sample counts, stack depth, and in-app frames. Use this stack as a starting point for investigation, not proof of the hang's cause.

The **Flamegraph** section shows the sampled call paths, including branches outside the representative stack trace. If the diagnostic contains multiple call trees, use the tree selector to inspect them individually.

When reading the graph:

* **Width represents sample count**, including samples in a frame's descendants. Wider paths were observed more often.
* Horizontal position does not represent execution order, and frame width is not an exact duration. MetricKit provides aggregate observations, not timestamped samples.
* Some call trees aggregate samples across threads. Do not assume every tree represents a single thread or the main thread.

### [Attachment Limits](https://docs.sentry.io/platforms/apple/guides/visionos/configuration/metric-kit.md#attachment-limits)

Flame graph attachments are subject to these limits:

* Attachments count toward your attachment quota, and the associated hang events count toward your error-event quota. No profiling quota is consumed. Attachment retention and access permissions apply.
* Each attachment is limited to 10 MiB. If the SDK cannot create it, for example because sample counts are invalid or the payload exceeds this limit, it falls back to storing the tree in the event's stack trace.
* Sentry symbolicates at most the first 2,500 frame entries in an attachment. Additional frames remain in the graph but may be unresolved. Missing debug information can also leave frames unresolved.

## [Attach the Raw Diagnostic Payload](https://docs.sentry.io/platforms/apple/guides/visionos/configuration/metric-kit.md#attach-the-raw-diagnostic-payload)

Starting with SDK version 8.29.0, enable `enableMetricKitRawPayload` to attach the original MetricKit diagnostic payload as JSON to the event.

The raw payload is separate from `flamegraph.json` and is not required for the flame graph viewer. Enabling both options sends both attachments and consumes additional attachment quota.

**Swift**

```swift
import Sentry

SentrySDK.start { options in
    options.dsn = "https://<key>@o<orgId>.ingest.sentry.io/<projectId>"
    options.enableMetricKit = true
    options.enableMetricKitRawPayload = true
}
```

**Objective-C**

```objc
@import Sentry;

[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.dsn = @"https://<key>@o<orgId>.ingest.sentry.io/<projectId>";
    options.enableMetricKit = YES;
    options.enableMetricKitRawPayload = YES;
}];
```

**Objective-C (SentryObjC)**

```objc
#import <SentryObjC/SentryObjC.h>

[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
    options.dsn = @"https://<key>@o<orgId>.ingest.sentry.io/<projectId>";
    options.enableMetricKit = YES;
    options.enableMetricKitRawPayload = YES;
}];
```
