metrickit

Collect and analyze on-device performance metrics and crash diagnostics from production iOS apps using Apple's MetricKit framework. It applies when wiring up MXMetricManager, handling MXMetricPayload or MXDiagnosticPayload, processing crash, hang, and disk-write diagnostics via MXCallStackTree, adding custom signpost metrics, or uploading telemetry to an analytics backend.

MetricKit delivers two kinds of reports. Metric payloads arrive roughly once every 24 hours with aggregated measurements — launch time, run time, CPU, peak memory, application responsiveness and hang time, animation scroll-hitch ratio, network and cellular transfer, and app-exit reasons. Diagnostic payloads carry crash, hang, CPU-exception, disk-write, and (on newer OS versions) app-launch diagnostics, each with a call-stack tree for triage. The guidance stresses registering an MXMetricManagerSubscriber as early as possible — in application(_:didFinishLaunchingWithOptions:) or App.init — because pastPayloads and pastDiagnosticPayloads only return reports generated since the shared manager was last allocated, and it shows both UIKit and SwiftUI registration.

Practical patterns include persisting each payload's raw jsonRepresentation() before processing, enqueuing metric and diagnostic handling on a background path, and inspecting the typed diagnostic arrays (crashDiagnostics, hangDiagnostics, diskWriteExceptionDiagnostics, cpuExceptionDiagnostics, and appLaunchDiagnostics) once the payload is durable. Availability is spelled out per type — MXMetricPayload from iOS 13, MXDiagnosticPayload from iOS 14 / macOS 12, and appLaunchDiagnostics from iOS 16. Call-stack trees are extracted via jsonRepresentation() and symbolicated with atos or by uploading dSYMs, and custom performance intervals are captured with mxSignpost against a MetricKit log handle, leaving the advanced dso, signpostID, and format parameters at their defaults. The document also references Xcode Organizer integration alongside scope boundaries, common mistakes, and a review checklist.