Docs

AppVitals iOS Metrics Reference

What Is This Document?

This document is a field-level reference for all performance attributes collected by AppVitals on iOS devices. It covers every metric field, its data type, unit of measurement, and a description of what it measures.

What Are Performance Attributes?

Performance attributes are measurable, time-series data points that describe how an app behaves on a real device at runtime. They are captured continuously (typically every 1–5 seconds) while the app is running, and aggregated to produce a health picture of the application.

They span multiple dimensions:

Dimension What It Covers
CPU How much processor time the app and system consume
Memory RAM usage including iOS-native physical footprint and VM pages
FPS & Rendering Smoothness of the UI, frame drops, hitches
GPU Tiler, renderer, and device GPU utilisation
Network Data sent/received, packet counts, link quality
Battery Charge level, temperature, power draw
Disk Storage space and I/O read/write throughput
Thermal Device heat and iOS thermal state (nominal/fair/serious/critical)
Process Thread count, Mach ports, IPC, syscalls, page faults
Crash & Stability Crashes, hangs (iOS equivalent of ANR), exceptions
Wake Locks Screen-on time, background wake activity
SQLite Query performance and database sizes
Startup & Page Transitions Time to display each ViewController
Jank & Hitches Skipped frames and hitch events
Per-Screen (ViewController) Per-screen aggregated health score

Data Collection

AppVitals collects iOS metrics via Instruments protocols over the device channel — no SDK is required inside the app. Data sources include:

  • sysmontap — CPU, memory, process, network, and disk counters
  • com.apple.instruments.server.services.graphics.opengl — GPU utilisation and frame timing
  • com.apple.instruments.server.services.diagnostics — FPS, hitch events, jank
  • com.apple.instruments.server.services.networking — network byte/packet counters
  • com.apple.instruments.server.services.activity — ViewController lifecycle and transitions
  • crashreporter / ips files — crash, hang, and exception capture
  • sysctl — device memory, CPU info, thermal state
  • IOKit — battery level, voltage, current, temperature

Data Types Used

Type Description
float64 64-bit floating-point number (e.g., 45.3%)
int 32-bit signed integer (e.g., thread count)
int64 64-bit signed integer for large accumulators (byte counts, ticks, page counts, nanosecond timestamps)
bool Boolean true/false value
string Text value
time.Time Timestamp
[]float64 Array of float64 values (e.g., per-core CPU %)
[]ExceptionInfo Array of crash/hang/exception detail objects
[]WakeLockInfo Array of wake lock detail objects
[]SQLiteQueryInfo Array of slow query detail objects
[]PageTransition Array of screen transition detail objects
[]JankEvent Array of jank/hitch event detail objects

Why int64? iOS has 71 fields using int64. Fields that accumulate over time — byte counts, CPU tick counters, VM page counts, IPC message counts, syscall counts, and durations — can grow far beyond the ~2.1 billion limit of a 32-bit int. int64 supports values up to ~9.2 quintillion, making it safe for long-running sessions.

CPU Metrics

Field Type Unit Description
AppPercent float64 % App's CPU usage as a percentage of total CPU. Indicates how hard the processor is working for this app — high values mean the app is computationally intensive.
SystemPercent float64 % Total system CPU usage percentage. Shows how busy the entire device CPU is, not just the app.
UserPercent float64 % User-mode CPU time percentage. Represents CPU time spent running app-level code rather than OS-level tasks.
IOWaitPercent float64 % I/O wait time percentage — typically 0 on iOS as the kernel handles I/O differently from Android.
Cores int count Number of CPU cores available on the device. More cores allow better multitasking and parallel processing.
PerCore []float64 % Per-core CPU usage percentages. Shows whether load is spread evenly or concentrated on specific cores.
FrequencyMHz int MHz Current CPU clock frequency. Higher frequency means faster processing but also more battery consumption.
CPUUsage float64 % Process CPU usage as reported by iOS native instrumentation (sysmontap). The primary per-process CPU metric on iOS.
CPUTotalUser int64 ticks Cumulative user-mode CPU ticks consumed by the process (iOS native). A running total used to calculate CPU usage trends over time.
CPUTotalSystem int64 ticks Cumulative kernel-mode CPU ticks consumed by the process (iOS native). Reflects OS-level operations triggered by the app.
CtxSwitch int64 count Total context switches for the process (iOS native). High values indicate the OS is frequently pausing and resuming the app's threads.
IntWakeups int64 count Interrupt wakeups attributed to the process (iOS native). Each wakeup pulls the CPU out of a low-power state — high values explain battery drain.

Memory Metrics

Field Type Unit Description
TotalPSS int64 KB Physical footprint — the primary iOS memory metric, equivalent to what Xcode's memory gauge displays. This is the recommended field to report for iOS app memory usage.
JavaHeap int64 KB Java heap (always 0 on iOS — included for cross-platform schema consistency).
NativeHeap int64 KB Native heap / resident size. Represents memory allocated by native C/Objective-C/Swift code.
Code int64 KB Memory occupied by the app's compiled code and frameworks.
Stack int64 KB Stack memory for all active threads. Each thread has its own stack for local variables and call frames.
Graphics int64 KB Graphics memory used by Metal textures, surfaces, and render targets. High values are expected for media-heavy apps.
PrivateOther int64 KB Private memory not covered by the above categories. Catches miscellaneous allocations.
System int64 KB Shared system memory attributed proportionally to the app. Memory shared across processes such as system frameworks.
SwapPSS int64 KB PSS in compressed/swap memory. iOS uses memory compression rather than traditional swap — rarely significant but non-zero under pressure.
DeviceTotal int64 KB Total RAM available on the device. A fixed device characteristic.
DeviceFree int64 KB RAM currently free on the device. Very low values mean the OS may start terminating background apps.
PhysFootprint int64 bytes Physical memory footprint as reported by iOS native instrumentation. Matches the value shown in Xcode's memory report.
MemResidentSize int64 bytes Resident set size — the physical pages currently mapped into the process's address space (iOS native).
MemVirtualSize int64 bytes Total virtual address space used by the process (iOS native). Much larger than physical memory; alone it does not indicate memory pressure.
MemAnon int64 bytes Anonymous memory — heap allocations not backed by a file (iOS native). Represents the app's runtime data allocations.
MemRPrvt int64 bytes Resident private memory — private pages currently in physical RAM (iOS native). Closest measure of memory exclusively held by this app.
MemRShrd int64 bytes Resident shared memory — shared pages currently in physical RAM (iOS native). Memory the app shares with the OS or other processes.
MemCompressed int64 bytes Memory currently held in iOS's memory compressor (iOS native). The OS compresses inactive pages instead of paging to disk.
MemPurgeable int64 bytes Memory that can be reclaimed by the OS without requiring a page-out (iOS native). The app can recreate this data if needed.
VMFreeCount int64 pages Free VM pages system-wide (iOS native). Decreasing values indicate growing memory pressure across all apps.
VMUsedCount int64 pages Used VM pages system-wide (iOS native).
VMWireCount int64 pages Wired (non-evictable) VM pages — kernel and locked memory (iOS native). The OS cannot reclaim these pages under any memory pressure.
VMCompressorCount int64 pages Pages held in the VM memory compressor (iOS native). Rising values indicate the OS is compressing inactive memory to free RAM.
VMPurgeableCount int64 pages Purgeable pages in the VM system (iOS native). These can be freed by the OS without data loss.
VMExtPageCount int64 pages External (file-backed) page count (iOS native). Memory mapped from files — frameworks, resources, and mapped databases.
VMIntPageCount int64 pages Internal (anonymous) page count (iOS native). Heap and stack allocations not backed by a file.
VMSpeculativeCount int64 pages Speculatively prefetched pages (iOS native). Pages read ahead of demand to improve future access speed.
PhysMemSize int64 bytes Total physical memory on the device (from sysctl hw.memsize). A fixed device characteristic.
VMPageInRate float64 pages/s Rate at which pages are being read into memory from storage. A sustained high rate indicates memory pressure.
VMPageOutRate float64 pages/s Rate at which pages are being written out or compressed. Rising rates signal the OS is struggling with memory demand.
VMSwapUsage int64 bytes Current swap/compression usage (iOS native). Non-zero values indicate the OS has begun compressing memory to cope with demand.

FPS Metrics

Field Type Unit Description
FPS float64 fps Frames per second. Target is 60 fps on standard displays and 120 fps on ProMotion displays — values below 30 fps are noticeable as stuttering.
FrameTimeMs float64 ms Average time to render one frame. Should stay under 16.67ms for 60 fps; under 8.33ms for 120 fps.
JankCount int count Number of frames that exceeded the 16.67ms threshold. Each jank event is a visible stutter the user may notice.
SlowFrames int count Frames that missed the vsync deadline (>17ms). Indicates how often the app failed to keep up with the display refresh rate.
FrozenFrames int count Frames taking longer than 700ms — the UI appeared completely frozen to the user during these frames.
TotalFrames int count Total frames rendered during the sample period. Used as the denominator for calculating jank percentages.

GPU Metrics

Field Type Unit Description
UsagePercent float64 % Overall GPU device utilisation percentage. High values during video playback or complex animations are expected but should not sustain at 100%.
DeviceUtilization float64 % Overall GPU device utilisation as reported by iOS Instruments (iOS native). Equivalent to UsagePercent but from a more granular source.
TilerUtilization float64 % GPU tiler utilisation — the geometry processing stage (iOS native). High values indicate complex 3D geometry or heavy UI layer composition.
RendererUtilization float64 % GPU renderer utilisation — the pixel shading stage (iOS native). High values indicate demanding textures or shader effects.

Network Metrics

Field Type Unit Description
RxBytes int64 bytes Total bytes received since session start. Reflects overall data downloaded by the app during the session.
TxBytes int64 bytes Total bytes transmitted since session start. Reflects overall data uploaded by the app during the session.
RxPackets int64 count Total network packets received. High packet counts with low byte counts can indicate chatty, inefficient network communication.
TxPackets int64 count Total network packets transmitted. Used alongside RxPackets to assess network communication efficiency.
WifiRxBytes int64 bytes Bytes received specifically over Wi-Fi. Useful for separating Wi-Fi and mobile data consumption.
WifiTxBytes int64 bytes Bytes transmitted specifically over Wi-Fi.
MobileRxBytes int64 bytes Bytes received over mobile data. Relevant for understanding cellular data plan consumption.
MobileTxBytes int64 bytes Bytes transmitted over mobile data.
RxBytesPerSec float64 bytes/s Download throughput calculated from the delta between RxBytes samples. Indicates the effective download speed during the session.
TxBytesPerSec float64 bytes/s Upload throughput calculated from the delta between TxBytes samples. Indicates the effective upload speed during the session.
NetBytesIn int64 bytes Process-level bytes received, as reported by iOS native instrumentation (sysmontap). More precise than system-wide RxBytes for per-app attribution.
NetBytesOut int64 bytes Process-level bytes transmitted, as reported by iOS native instrumentation.
NetPacketsIn int64 count System-wide received packets as reported by iOS native instrumentation.
NetPacketsOut int64 count System-wide transmitted packets as reported by iOS native instrumentation.

Battery Metrics

Field Type Unit Description
Level int % Battery charge level (0–100). Tracks how much battery the device had at the time of the session.
Temperature float64 °C Battery temperature. Elevated temperatures indicate the device is under heavy load or charging while in use.
Voltage float64 mV Battery voltage. Drops as the battery drains; unusually low voltage can indicate a degraded battery.
Current float64 mA Battery current draw (negative = discharging, positive = charging). High negative values indicate significant power consumption.
Power float64 mW Power consumption calculated as Voltage × Current. The most direct indicator of how much energy the app is using.
IsCharging bool — Whether the device is currently charging (iOS native). Context for interpreting battery level changes during the session.

Disk Metrics

Field Type Unit Description
TotalBytes int64 bytes Total internal storage capacity of the device. A fixed device characteristic.
UsedBytes int64 bytes Storage currently used on the device. High values with low FreeBytes may cause app instability or failed writes.
FreeBytes int64 bytes Storage currently free. Very low free space can cause crashes, failed downloads, and database write errors.
ReadBytes int64 bytes Total bytes read from disk since boot. High values relative to session length can indicate excessive file I/O.
WrittenBytes int64 bytes Total bytes written to disk since boot. Persistently high write activity can cause thermal issues and flash storage wear.
DiskReadOps int64 count Total disk read operations as reported by iOS native instrumentation. Complements ReadBytes by counting individual operations regardless of size.
DiskWriteOps int64 count Total disk write operations (iOS native). High counts with small sizes suggest many small random writes, which are slower than sequential I/O.
DiskBytesRead int64 bytes System-wide bytes read, as reported by iOS native instrumentation. Broader than ReadBytes which is process-scoped.
DiskBytesWritten int64 bytes System-wide bytes written (iOS native).

Thermal Metrics

Field Type Unit Description
CPUTemp float64 °C CPU temperature. Values above ~85°C typically trigger throttling that reduces app performance.
GPUTemp float64 °C GPU temperature. High GPU temperatures during video playback or rendering indicate thermal stress.
BatteryTemp float64 °C Battery temperature. High values (above 45°C) risk battery health and users will notice the device feeling hot.
SkinTemp float64 °C Device surface/skin temperature — what the user physically feels when holding the device.
ThrottleState int level Thermal throttle level (0 = normal, higher = more throttled). When throttled the OS reduces CPU/GPU speed to cool the device, causing visible slowdowns.
ThermalStatus string — iOS thermal state: "nominal" (normal), "fair" (slightly warm), "serious" (hot, performance limited), or "critical" (very hot, severe throttling). This is the most direct, customer-explainable thermal signal on iOS.

Process Metrics

Field Type Unit Description
PID int — Process ID of the app. Used internally to identify the app's process when correlating metrics.
ThreadCount int count Number of active threads in the app process. Unusually high thread counts can indicate thread leaks or excessive concurrency.
PPID int — Parent process ID (iOS native). Identifies which process launched this app process.
PGID int — Process group ID (iOS native). Groups related processes together at the OS level.
UID int — User ID of the process (iOS native). On iOS all apps run as the mobile user — typically UID 501.
Name string — Process name as registered with the OS (iOS native). Usually matches the app binary name.
ResponsiblePID int — The PID of the process responsible for this app (iOS native). Relevant for extensions where the host app is responsible.
ProcStatus int — Process status code (iOS native). Indicates whether the process is running, sleeping, stopped, or zombie.
AppSleep bool — Whether the app is currently suspended in the background (iOS native). Suspended apps consume no CPU but remain in memory.
MachPortCount int count Number of Mach ports open (iOS native). Mach ports are iOS's IPC mechanism — high counts can indicate port leaks that will eventually crash the app.
MsgSent int64 count IPC messages sent by the process (iOS native). Tracks inter-process communication volume.
MsgRecv int64 count IPC messages received by the process (iOS native). High combined MsgSent/MsgRecv values indicate heavy inter-process activity.
SysCallsUnix int64 count Total Unix system calls made by the process (iOS native). Reflects how often the app requests OS services like file access and network.
SysCallsMach int64 count Total Mach system calls made by the process (iOS native). Mach calls are iOS's lower-level OS interface below Unix.
Faults int64 count Total page faults for the process (iOS native). High page fault counts indicate the app is accessing memory pages that are not currently loaded, causing performance delays.
VMPageIns int64 count VM pages paged in for the process (iOS native). Each page-in means the app demanded a memory page from storage — high values indicate memory pressure.

UI Metrics

Field Type Unit Description
ViewCount int count Number of UIViews currently on screen. Very high counts can slow layout passes and rendering.
NestingDepth int levels Maximum view hierarchy depth. Deep nesting (>10 levels) increases layout calculation time and can cause rendering slowdowns.
ActivitiesCount int count Number of ViewControllers currently in the navigation stack. High stack depths may indicate the app is not releasing dismissed screens.
CurrentActivity string — The name of the currently active ViewController. Identifies which screen the user was on when a metric was captured.

GC Metrics

Field Type Unit Description
GCCount int count Number of garbage collection events during the sample period. Frequent GC can cause brief pauses and UI jank.
GCPauseMs float64 ms Total pause time caused by GC events. Represents time the app's execution was interrupted for memory cleanup.
GCFreedBytes int64 bytes Total bytes freed by GC events. Indicates how much memory the app was releasing per sample period.
GCFreedObjects int64 count Number of objects freed by GC. High object churn (many allocations and frees) can drive frequent GC pauses.

Crash & Stability Metrics

Field Type Unit Description
CrashCount int count Number of crashes detected during the session. Each crash represents the app forcibly closing — the most direct signal of an unstable session.
ANRCount int count Number of hangs detected — the iOS equivalent of an Android ANR. A hang means the app's main thread was blocked and the UI stopped responding to user input.
ExceptionCount int count Number of exceptions detected during the session. High exception counts indicate error-prone code paths even when the app didn't fully crash.
Crashes []ExceptionInfo — Detailed information for each crash event in the session.
ANRs []ExceptionInfo — Detailed information for each hang event in the session.
Exceptions []ExceptionInfo — Detailed information for each exception in the session.

ExceptionInfo Structure

Field Type Unit Description
Timestamp time.Time — When the crash or exception occurred. Helps correlate with a specific point in the user's session.
Type string — Exception type (e.g., EXC_BAD_ACCESS, NSException, SIGABRT). Identifies the category of failure.
Message string — The exception message text. Provides context about what specifically went wrong.
Location string — File and line number where the exception occurred. Pinpoints the exact code location for engineering investigation.

File Descriptor Metrics

Field Type Unit Description
OpenFDs int count Number of file descriptors currently open by the app. Tracks open files, sockets, and pipes.
MaxFDs int count The system limit for open file descriptors. If OpenFDs approaches this limit, the app will start failing to open new files or connections.
SocketFDs int count Number of open socket file descriptors. High values may indicate lingering network connections not being closed.
PipeFDs int count Number of open pipe file descriptors. Used for inter-process communication.
FileFDs int count Number of regular file descriptors currently open. High values indicate the app is reading/writing many files simultaneously.
OtherFDs int count File descriptors of types not covered by the above categories.
FDGrowthRate float64 fds/s Rate at which file descriptors are being opened. A steadily increasing rate indicates a descriptor leak that will eventually crash the app.

Input Latency Metrics

Field Type Unit Description
TouchToDisplayMs float64 ms Time from a touch event to the resulting display update appearing on screen. This is what the user perceives as tap responsiveness.
InputDispatchMs float64 ms Time for the system to route the input event to the correct responder in the app.
InputDeliveryMs float64 ms Time for the event to be delivered to the app after dispatch. Delays here indicate the app's event queue is backed up.
PendingEvents int count Number of input events queued but not yet processed by the app. A growing queue indicates the app cannot keep up with user input.

GfxInfo Metrics

Field Type Unit Description
Frames0to16ms int count Frames rendered in 0–16ms — good, on-time frames the user experiences as smooth.
Frames16to32ms int count Frames that took 16–32ms — slightly slow, causing minor stutter attentive users may notice.
Frames32to50ms int count Frames that took 32–50ms — noticeably slow, resulting in visible stuttering during scrolling or animation.
Frames50plus int count Frames taking 50ms or more — these appear frozen or completely stuck to the user.
TotalFramesGfx int count Total frames in the gfxinfo sample window. Used as the baseline for calculating jank percentages.
FrameTimeP50Ms float64 ms The 50th percentile (median) frame render time — what a typical frame takes.
FrameTimeP90Ms float64 ms The 90th percentile frame time — 90% of frames render within this duration.
FrameTimeP95Ms float64 ms The 95th percentile frame time — only 5% of frames are slower than this.
FrameTimeP99Ms float64 ms The 99th percentile frame time — represents the slowest 1% of frames, the worst-case rendering experience.
DrawTimeMs float64 ms Time spent issuing Metal/OpenGL draw commands to the GPU.
SyncTimeMs float64 ms Time spent waiting for the render sync barrier before the frame can proceed.
ProcessTimeMs float64 ms Time taken to process and compose the frame after drawing.
CommandIssueMs float64 ms Time taken to issue GPU commands for rendering.
SwapBuffersMs float64 ms Time to present the rendered Metal buffer to the display.
JankyFrames int count Total count of janky frames (>16.67ms). Directly measures rendering quality from the user's perspective.
JankyFramePercent float64 % Percentage of all frames that were janky. Above 10% is generally noticeable as an unsmooth experience.

Wake Lock Metrics

Field Type Unit Description
ActiveWakeLocks int count Currently held wake locks. Typically 0 on iOS as the concept is Android-native — included for cross-platform schema consistency.
PartialWakeLockMs int64 ms Total duration a partial wake lock was held — keeps the CPU running even when the screen is off. Prolonged values explain background battery drain.
FullWakeLockMs int64 ms Total duration a full wake lock was held — keeps the screen on. High values mean the app kept the screen on for extended periods.
ScreenOnTimeMs int64 ms Total time the screen was on during the session. Directly correlated with battery consumption.
DozeTimeMs int64 ms Total time the device spent in low-power/doze mode. Doze conserves battery by restricting background activity.
WakeLockDetails []WakeLockInfo — Detailed list of active wake locks held during the session.

WakeLockInfo Structure

Field Type Unit Description
Tag string — Wake lock tag/name assigned by the app. Identifies which component acquired the lock.
Type string — Wake lock type: partial, full, screen_dim, etc. Describes what the lock is preventing the device from doing.
DurationMs int64 ms Duration this specific wake lock instance was held. Identifies which lock is responsible for extended wake activity.
Package string — Bundle ID of the app holding the wake lock. Confirms which app is responsible.

SQLite Metrics

Field Type Unit Description
QueryCount int count Total SQL queries executed during the sample period. High counts indicate a database-heavy feature is being exercised.
SlowQueryCount int count Number of queries that took longer than 16ms. Slow queries block the thread they run on and can cause UI jank if executed on the main thread.
AvgQueryTimeMs float64 ms Average query execution time across all queries. Baseline indicator of database performance.
MaxQueryTimeMs float64 ms The slowest single query observed. A very high max points to a specific problematic query worth investigating.
TotalQueryTimeMs float64 ms Total time spent in database queries during the session. Reflects cumulative database load.
DatabaseSizeKB int64 KB Size of the SQLite database file on disk. Unexpectedly large databases slow down queries and consume significant storage.
WALSizeKB int64 KB Size of the Write-Ahead Log file. A large WAL indicates many uncommitted transactions and can degrade database performance if not checkpointed.
SlowQueries []SQLiteQueryInfo — Detailed list of slow queries captured during the session.

SQLiteQueryInfo Structure

Field Type Unit Description
Timestamp time.Time — When the slow query was executed. Used to correlate with user actions in the session.
Query string — The SQL query text (truncated if long). Identifies the specific operation that was slow.
DurationMs float64 ms Execution time for this specific query instance.
Table string — The database table name if parseable from the query. Helps identify which data store is the bottleneck.

Network Detail Metrics

Field Type Unit Description
NetworkType string — The active network connection type: "wifi", "mobile", or "none". Establishes the baseline for evaluating network performance context.
WifiRSSI int dBm Wi-Fi signal strength in dBm — more negative means weaker signal (e.g., -50 is strong, -85 is weak and unreliable).
WifiLinkSpeed int Mbps Wi-Fi link speed negotiated between the device and the access point. Low link speeds limit throughput regardless of the internet connection speed.
WifiFrequency int MHz The Wi-Fi band in use — 2400 MHz (2.4 GHz, longer range, lower speed) or 5000 MHz (5 GHz, shorter range, higher speed).
MobileSignal int dBm Mobile cellular signal strength. Weak signal causes slower speeds and higher latency on mobile data.
DNSLookupMs float64 ms Time to resolve a hostname to an IP address. High values indicate DNS issues that add latency to every network request.
TCPConnectMs float64 ms Time to establish a TCP connection to a server. Reflects network round-trip latency between the device and the server.
TLSHandshakeMs float64 ms Time to complete the TLS/SSL security handshake. Adds to total connection setup time before any data transfer begins.
PacketLossPercent float64 % Estimated percentage of packets lost in transit. Any packet loss causes retransmissions and visible slowdowns in streaming or downloads.
Jitter float64 ms Variation in packet arrival times. High jitter degrades real-time streaming quality even when average throughput is acceptable.

Startup & Page Transition Metrics

Field Type Unit Description
Transitions []PageTransition — All ViewController transitions recorded during the session. The full navigation history for the session.
AvgTransitionMs float64 ms Average transition time across all screen changes. Reflects overall navigation responsiveness during the session.
MaxTransitionMs int64 ms The slowest screen transition observed. Captures the worst-case navigation experience in the session.
SlowTransitions int count Number of transitions that exceeded 500ms. Each slow transition is a moment the user visibly waited for a screen to appear.

PageTransition Structure

Field Type Unit Description
Timestamp time.Time — When the transition occurred during the session.
FromActivity string — The ViewController the user was navigating away from.
ToActivity string — The ViewController being presented to the user.
Package string — The app Bundle ID involved in the transition.
DurationMs int64 ms Time to display the new screen (TTID — Time To Initial Display). This is what the user perceives as screen load time.
FullyDrawnMs int64 ms Time until the screen is fully populated with content (TTFD — Time To Fully Drawn). A screen may appear quickly but take longer to load actual data into its views.

Jank & Hitch Metrics

Field Type Unit Description
Events []JankEvent — All jank and hitch events recorded during the session.
TotalSkippedFrames int64 count Cumulative frames skipped throughout the entire session. Each skipped frame is a moment of stuttering the user experienced.
SlowFrameCount int count Count of individual slow frame events. Tracks how many times the app failed to render a frame on time.
SlowDispatchCount int count Count of slow input dispatch events — times when the system was slow to route user input.
SlowDeliveryCount int count Count of slow event delivery events — times when delivering input to the app took longer than expected.

JankEvent Structure

Field Type Unit Description
Timestamp time.Time — When the jank or hitch occurred during the session.
Type string — Event type — on iOS this is reported as "hitch", meaning a frame that was delivered late to the display.
FramesOrMs int64 count/ms For skipped frame events: number of frames skipped. For hitch/slow events: duration in ms the frame was late.
Activity string — The active ViewController when the jank or hitch occurred. Identifies which screen has the rendering issue.

Device Info

Field Type Unit Description
ID string — Device UDID — the unique identifier for this physical iOS device.
Name string — Human-readable device name as set by the user (e.g., "John's iPhone 15 Pro").
Platform string — Always "ios" for iOS devices.
Brand string — Always "Apple" for iOS devices.
Model string — Device model identifier (e.g., "iPhone16,1"). Helps identify the exact hardware generation.
Manufacturer string — Always "Apple" for iOS devices.
OSVersion string — iOS version string (e.g., "iOS 17.2"). Helps correlate issues with specific iOS versions.
SDKVersion int — iOS SDK version number. Used to identify OS-specific behaviour.
ScreenWidth int px Screen width in pixels. Affects layout rendering and resolution-dependent performance.
ScreenHeight int px Screen height in pixels.
UDID string — Device unique identifier (iOS native). Same as ID — the device's persistent hardware identifier.
ProductType string — Product type string as known to Apple (e.g., "iPhone16,1") (iOS native). More specific than Model.
BuildVersion string — iOS build version string (e.g., "21C62") (iOS native). Identifies the exact OS build, useful for correlating issues across minor Apple updates.

App Info

Field Type Unit Description
PackageName string — The app's Bundle ID (e.g., com.example.app). Uniquely identifies the app on the device and in the App Store.
AppName string — The app's display name as shown to the user.
Version string — The version string (CFBundleShortVersionString, e.g., "5.2.1") — the human-readable version shown in the App Store.
VersionCode int — The build number (CFBundleVersion). Used internally to distinguish builds when the version name is the same.
UID int — User ID of the process — always 0 on iOS as all apps run as the same system user.

Per-Screen (ViewController) Metrics

Field Type Unit Description
Name string — The ViewController class name identifying this screen.
VisitCount int count Number of times this screen was visited during the session. High counts indicate frequently used screens worth monitoring closely.
AvgLoadTimeMs float64 ms Average TTID (Time To Initial Display) across all visits to this screen. Reflects the typical wait time when navigating here.
MaxLoadTimeMs int64 ms The slowest observed TTID for this screen. Captures worst-case user experience on this screen.
JankEventCount int count Number of jank or hitch events that occurred while the user was on this screen.
CrashCount int count Number of crashes that occurred on this screen. Identifies which screens are crash-prone.
ANRCount int count Number of hangs that occurred on this screen. Indicates where the app became unresponsive to user input.
AvgFPS float64 fps Average frames per second while this screen was active. Below 30 fps is noticeably unsmooth to users.
AvgCPU float64 % Average CPU usage while this screen was active. High values on specific screens explain battery drain or thermal issues.
AvgMemoryMB float64 MB Average memory usage while this screen was active. Identifies memory-heavy screens that may cause pressure on low-RAM devices.
TotalTimeMs int64 ms Total time the user spent on this screen across the session.
SkippedFrames int64 count Total frames skipped while the user was on this screen. Direct measure of rendering quality per screen.
SlowFrameCount int count Count of slow frame events specific to this screen.
IssueCount int count Total issue count combining jank, crash, and hang events for this screen. A single aggregate quality signal per screen.
Score int 0–100 Overall health score for this screen — 80–100 is good, 50–79 is moderate, below 50 indicates significant performance issues.
Level string — Score tier: "good", "moderate", or "poor". The quickest signal of whether this screen is performing acceptably for users.