metrickit
Use when collecting or analyzing production iOS or iPadOS performance telemetry with MetricKit, including iOS 27 MetricManager async metric or diagnostic reports, hang or crash triage, custom signposts, extended launch measurement, durable export, or iOS 26 MXMetricManager compatibility.
Install / Use
npx skills add dpearson2699/swift-ios-skills --skill metrickitInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of metrickit
metrickit scores 89/100 on our quality scale, 1674th of 4,700 Development & Engineering skills we index (top 36%).
Its SKILL.md is 14 KB long, well organised into 16 sections with 6 code examples: a thorough specification that gives an agent plenty to work with.
With 1,143 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-10-31 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 86/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
metrickit compared with similar skills
All 4 of these similar skills score higher than metrickit; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| metrickit (this skill)by dpearson2699 | 89 | 1.1k | 4mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install metrickit?
- Run
npx skills add dpearson2699/swift-ios-skills --skill metrickit. The install tabs above show the steps for each supported agent. - Which AI agents does metrickit work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is metrickit safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 86/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is metrickit still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: metrickit description: Use when collecting or analyzing production iOS or iPadOS performance telemetry with MetricKit, including iOS 27 MetricManager async metric or diagnostic reports, hang or crash triage, custom signposts, extended launch measurement, durable export, or iOS 26 MXMetricManager compatibility.
MetricKit
Use MetricKit for low-overhead production telemetry that complements local Instruments and Xcode Organizer analysis. On iOS and iPadOS 27, prefer the Swift-first MetricManager report sequences. Keep MXMetricManager only in an explicit iOS 26 compatibility branch.
Beta-sensitive: The iOS/iPadOS 27 surface below is based on Apple's current beta documentation. It has not been locally compiler-verified because Xcode 27 is unavailable in this environment. Re-check the linked Apple documentation and compile with the shipping Xcode 27 SDK before release.
Load MetricKit Extended and Compatibility Patterns when implementing durable ingestion, detailed report analysis, or the iOS 26 compatibility path.
Contents
- MetricManager Setup
- Receiving Metric Reports
- Receiving Diagnostic Reports
- Key Metric Results
- Call Stack Trees
- Custom Signpost Metrics
- Durable Export and Upload
- Extended Launch Measurement
- iOS 26 Compatibility
- Xcode Organizer
- Scope Boundaries
- Common Mistakes
- Review Checklist
- References
MetricManager Setup
At app launch, create and retain one long-lived MetricManager. Start exactly one consumer task for metricReports and one for diagnosticReports.
Both properties expose nonthrowing AsyncSequence values:
metricReports: some AsyncSequence<MetricReport, Never>diagnosticReports: some AsyncSequence<DiagnosticReport, Never>
Apple documents that concurrent consumers of one sequence can receive nondeterministic subsets. Fan out only after the single consumer receives and durably stores a report; delayed subscription can miss reports.
import MetricKit
@available(iOS 27.0, *)
final class MetricsService {
private let manager = MetricManager()
private var metricTask: Task<Void, Never>?
private var diagnosticTask: Task<Void, Never>?
func start(
persistMetric: @escaping @Sendable (MetricReport) async -> Void,
persistDiagnostic: @escaping @Sendable (DiagnosticReport) async -> Void
) {
guard metricTask == nil, diagnosticTask == nil else { return }
let manager = manager
metricTask = Task {
for await report in manager.metricReports {
await persistMetric(report)
}
}
diagnosticTask = Task {
for await report in manager.diagnosticReports {
await persistDiagnostic(report)
}
}
}
deinit {
metricTask?.cancel()
diagnosticTask?.cancel()
}
}
The persistence closures are application-specific. Implement them with the durable-first workflow below rather than dropping, logging only, or directly uploading each report. If state-scoped metrics are needed, construct the manager with the documented init(enabledStateReportingDomains:) initializer and the required domains.
Receiving Metric Reports
MetricReport is Codable and Sendable. It describes an interval through:
timeRange: DateInterval- optional
environmentmetadata intervalEntriesfor full-day and shorter interval measurementsstateEntriesfor measurements associated with application states
Metric reports normally arrive on a daily cadence. Persist the complete report before extracting individual results.
For daily analysis, read the documented fullDayEntry and switch over its MetricResult values:
let entry = report.intervalEntries.fullDayEntry
for result in entry.values {
switch result {
case .hangTime(let metric):
analyzeHangTime(metric)
case .peakMemory(let metric):
analyzePeakMemory(metric)
case .timeToFirstDraw(let metric):
analyzeLaunch(metric)
case .signpostInterval(let metric):
analyzeSignpost(metric)
@unknown default:
preserveUnknownMetric(result)
}
}
Use @unknown default so a beta or future result does not make the ingestion pipeline brittle. Preserve the raw encoded report even when the current app does not understand a result.
Receiving Diagnostic Reports
DiagnosticReport is Codable and Sendable. It contains a timeRange, required environment metadata, and one DiagnosticResult.
Diagnostics are individual, event-based reports intended for prompt delivery when MetricKit produces them. Do not assume every crash, hang, or resource event generates a report; system sampling and eligibility still apply.
After durable storage, route the result explicitly:
switch report.result {
case .crash(let diagnostic):
analyzeCrash(diagnostic)
case .hang(let diagnostic):
analyzeHang(diagnostic)
case .cpuException(let diagnostic):
analyzeCPUException(diagnostic)
case .diskWriteException(let diagnostic):
analyzeDiskWrites(diagnostic)
case .appLaunch(let diagnostic):
analyzeLaunch(diagnostic)
case .memoryException(let diagnostic):
analyzeMemory(diagnostic)
@unknown default:
preserveUnknownDiagnostic(report)
}
The iOS/iPadOS 27 diagnostic types are CrashDiagnostic, HangDiagnostic, CPUExceptionDiagnostic, DiskWriteExceptionDiagnostic, AppLaunchDiagnostic, and MemoryExceptionDiagnostic. The memory-exception case is new in iOS 27.
Useful fields include:
| Diagnostic | Important fields |
|---|---|
| CrashDiagnostic | callStackTree, exception type/code/reason, signal, virtual-memory region, termination category/reason |
| HangDiagnostic | callStackTree, hangDuration |
| CPUExceptionDiagnostic | callStackTree, totalCPUTime, totalSampledTime |
| DiskWriteExceptionDiagnostic | callStackTree, totalBytesWritten |
| AppLaunchDiagnostic | callStackTree, launchDuration |
| MemoryExceptionDiagnostic | callStackTree |
Key Metric Results
Choose a small telemetry vocabulary that matches the investigation rather than exporting every result. Prioritize the relevant categories: responsiveness and terminations; runtime, CPU, memory, network, and storage; or launch, display/GPU, and custom intervals.
Aggregate by app version and environment metadata, compare distributions rather than single values, and correlate regressions with releases. Avoid treating a daily aggregate as a precise trace of one user action.
Load the Key Metric Result Catalog when mapping exact MetricResult cases into a parser or dashboard.
Call Stack Trees
The iOS 27 CallStackTree replaces MXCallStackTree. It is Codable and Sendable and exposes:
forEachFramefor frame traversalcallStackThreadsfor thread-oriented analysisbinaryInfofor image and binary metadata
Store the complete diagnostic report before flattening or symbolication. Preserve binary identifiers and offsets so server-side symbolication can use matching archives and dSYMs.
Custom Signpost Metrics
Create an OS log through the manager, then use mxSignpost for begin/end measurement:
let log = manager.logHandle(category: "ImagePipeline")
mxSignpost(.begin, log: log, name: "Decode")
await decodeImage()
mxSignpost(.end, log: log, name: "Decode")
MetricKit exposes the aggregate as MetricResult.signpostInterval. Do not search for a signpostMetrics array on MetricReport.
Use mxSignpost when MetricKit resource measurement is required. Apple documents that intervals created with OSSignposter and a MetricKit log handle do not populate the resource-measurement fields that mxSignpost provides.
Keep high-volume local tracing separate from the small set of stable production intervals used for MetricKit aggregation.
Durable Export and Upload
Treat report delivery as an at-least-once ingestion problem:
- Encode the complete
MetricReportorDiagnosticReportwithJSONEncoder. - Atomically enqueue the bytes in an app-owned durable outbox.
- Record report type, schema version, app version, and a stable deduplication key.
- Acknowledge local processing only after the enqueue succeeds.
- Upload later with retry, backoff, batching, and retention limits.
- Mark the outbox item uploaded only after the server accepts it.
let data = try JSONEncoder().encode(report)
try await durableOutbox.enqueue(data, kind: .metric)
durableOutbox is an application-owned abstraction, not a MetricKit API. Do not perform a synchronous network upload inside the sequence consumer.
Durable local storage is the recovery mechanism for reports received through the modern sequences; do not make successful ingestion depend on an assumed modern backfill API.
Extended Launch Measurement
Use trackLaunchTask(id:onTrackingError:_:) on the manager for work that extends beyond time to first draw:
await manager.trackLaunchTask(
id: "bootstrap-data",
onTrackingError: { error in
recordLaunchTrackingError(error)
}
) {
await bootstrapApplication()
}
The API is @MainActor and has synchronous and asynchronous overloads. The task closure's result and thrown error propagate to the caller; a MetricManager.LaunchTaskError is reported through onTrackingError without interrupting the tracked work. Results appear as MetricResult.extendedLaunch.
Use stable LaunchTaskID values and track only launch-critical work.
iOS 26 Compatibility
For an app that still deploys to iOS 26, use an availability boundary:
- iOS/iPadOS 27: use
MetricManagerand consume both async report sequences. - iOS/iPadOS 26 and earlier supported releases: use
MXMetricManager.shared, anMXMetricManagerSubscriber, and the legacy payload callbacks.
The legacy APIs remain the only documented branch with pastPayloads and pastDiagnosticPayloads. MXMetricManager is deprecated in iOS 27, so isolate it behind availability checks rather than mixing legacy payloads into the modern pipeline.
Load iOS 26 Compatibility for the full subscriber, legacy signpost, past-payload, and extended-launch patterns.
Xcode Organizer
Use Xcode Organizer to inspect Apple-aggregated production metrics, hangs, crashes, and regressions before building a custom backend. Use direct MetricKit ingestion when the product needs custom correlation, retention, alerting, or integration with an existing observability system.
Do not expect development-device runs to reproduce the population, cadence, or aggregation of production reports.
Scope Boundaries
| Task | Use instead |
|---|---|
| Reproduce a problem locally or record a detailed trace | debugging-instruments |
| Diagnose retained objects or memory graph paths | ios-memgraph-analysis |
| Tune SwiftUI invalidation, identity, or scrolling code | swiftui-performance |
| Study structured EnergyKit impact data | energykit |
| Design general logging and os_signpost strategy | swift-logging |
MetricKit identifies production symptoms and trends. Route the actual code fix to the skill that owns the affected subsystem.
Common Mistakes
| Mistake | Correction |
|---|---|
| Uploading directly in the sequence loop | Encode and enqueue locally first; upload asynchronously later. |
| Assuming every diagnostic event produces a report | Treat diagnostics as sampled, system-produced evidence. |
| Looking for pastPayloads on `MetricManag
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
