Docs

AppVitals Android Metrics Reference

What Is This Document?

This document is a field-level reference for all performance attributes collected by AppVitals on Android 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 broken down by heap, native, graphics, etc.
FPS & Rendering Smoothness of the UI, frame drops, jank
GPU Graphics processor 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 throttling state
Process Thread count, file descriptors, PIDs
Crash & Stability Crashes, ANRs, exceptions
Wake Locks Screen-on time, background wake activity
SQLite Query performance and database sizes
Launch Timing Cold, warm, and hot start durations
Page Transitions Time to display each screen
Jank Skipped frames and stutter events
Per-Screen (Activity) Per-screen aggregated health score

Data Collection

AppVitals collects Android metrics via ADB shell commands — no SDK is required inside the app. Data sources include:

  • dumpsys meminfo — memory breakdown
  • dumpsys gfxinfo — frame timing and jank
  • cat /proc/stat and /proc/<pid>/stat — CPU jiffies
  • dumpsys batterystats — battery and wake lock data
  • dumpsys cpuinfo — per-process CPU usage
  • adb shell dumpsys activity — activity/screen info
  • adb shell netstat / traffic stats — network counters
  • df -h / /proc/diskstats — disk usage and I/O
  • logcat — crash, ANR, exception capture
  • dumpsys SurfaceFlinger — GPU and frame info
  • am start -W — launch timing
  • lsof — file descriptor counts

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, jiffies, nanoseconds, durations)
string Text value
time.Time Timestamp
[]float64 Array of float64 values (e.g., per-core CPU %)
[]ExceptionInfo Array of crash/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 event detail objects

Why int64? Fields that accumulate over time (byte counts, CPU jiffies, nanosecond timestamps, durations) can grow 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 as a percentage of CPU. High values mean the CPU is sitting idle waiting for storage reads/writes to complete.
Cores int count Number of CPU cores available on the device. More cores generally allow better multitasking.
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.
User int64 jiffies Cumulative CPU time spent in user mode since boot (from /proc/stat). A raw system counter used to calculate CPU usage trends over time.
Nice int64 jiffies Cumulative CPU time for low-priority background processes. High values indicate significant background activity running at reduced priority.
System int64 jiffies Cumulative CPU time spent in kernel/system mode. Reflects how much time the OS itself spends on behalf of all processes.
Idle int64 jiffies Cumulative CPU idle time. A high idle value means the device CPU has spare capacity.
IOWait int64 jiffies Cumulative time the CPU spent waiting for I/O operations. High values point to storage bottlenecks slowing the device down.
IRQ int64 jiffies Cumulative time servicing hardware interrupts. Reflects how often hardware events (like touch, network) are demanding CPU attention.
SoftIRQ int64 jiffies Cumulative time servicing software interrupts. Used internally to track kernel-level deferred work.
UTime int64 jiffies User-mode CPU time consumed by the app process specifically. Directly tracks how much CPU the app itself has used.
STime int64 jiffies Kernel-mode CPU time consumed by the app process. Shows how often the app triggered OS-level operations like file access or network calls.
CUTime int64 jiffies User-mode CPU time for child processes spawned by the app. Relevant if the app launches sub-processes.
CSTime int64 jiffies Kernel-mode CPU time for child processes spawned by the app. Tracks OS-level work done by sub-processes of the app.

Memory Metrics

Field Type Unit Description
TotalPSS int64 KB Proportional Set Size — the total memory attributed to the app, including its share of shared libraries. This is the primary memory metric to report for Android apps.
JavaHeap int64 KB Java/Dalvik heap memory currently in use. Represents objects allocated by the app's Java/Kotlin code.
NativeHeap int64 KB Native (C/C++) heap memory in use. Memory allocated by native libraries or the Android media framework.
Code int64 KB Memory used by the app's code — APK, compiled DEX, and OAT files.
Stack int64 KB Stack memory for all active threads in the app. Each thread has its own stack for local variables and function calls.
Graphics int64 KB GPU/graphics memory used — textures, surfaces, and render buffers. High values are expected for media-heavy apps.
PrivateOther int64 KB Private memory not covered by the above categories. Catches miscellaneous allocations not attributed elsewhere.
System int64 KB Shared system memory attributed proportionally to the app. Memory shared with other processes (e.g., system fonts, shared libraries).
SwapPSS int64 KB PSS held in swap space. Indicates memory the OS has moved out of RAM to free up space for other processes.
DeviceTotal int64 KB Total RAM available on the device. A fixed device characteristic.
DeviceFree int64 KB RAM currently free on the device. Low values indicate the device is under memory pressure and may start killing background processes.

FPS Metrics

Field Type Unit Description
FPS float64 fps Frames rendered per second. The target is 60 fps for smooth UI — values below 30 fps are noticeable to users as stuttering.
FrameTimeMs float64 ms Average time to render one frame. Should be under 16.67ms for 60 fps; higher values result in dropped frames.
JankCount int count Number of frames that caused a perceptible jank (exceeded 16.67ms). Each jank event is a visible stutter the user may notice.
SlowFrames int count Frames that missed the vsync deadline (>17ms). Indicates how frequently 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 when calculating jank percentage.
IntendedVsync int64 ns The intended vsync timestamp from Android's Choreographer. Marks when a frame was supposed to start rendering.
Vsync int64 ns The actual vsync timestamp when the frame started rendering. Comparing with IntendedVsync reveals scheduling delays.
FrameCompleted int64 ns Timestamp when the frame finished rendering and was presented. Used to calculate actual frame duration.

GPU Metrics

Field Type Unit Description
UsagePercent float64 % GPU utilisation as a percentage. High values indicate the app is GPU-bound — common in video playback, games, and complex animations.

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

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 can 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 mean the app is consuming significant power.
Power float64 mW Power consumption calculated as Voltage × Current. The most direct indicator of how much energy the app is using.

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.
FreeBytes int64 bytes Storage currently free. Very low free space can cause crashes, failed downloads, and database 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. Persistent high write activity can cause thermal issues and storage wear.

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) indicate risk to battery health and may be reported by the user as 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 down, causing visible slowdowns.
ThermalStatus string — Human-readable thermal state label (e.g., "normal", "light", "moderate", "severe"). Directly communicates how hot the device was during the session.

Process Metrics

Field Type Unit Description
PID int — Process ID of the app. Used internally to identify the app process when pulling metrics.
ThreadCount int count Number of active threads in the app process. Unusually high thread counts can indicate thread leaks or excessive concurrency.

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 Application Not Responding events. An ANR means the app's UI thread was blocked for more than 5 seconds — the user sees a "App not responding" dialog.
ExceptionCount int count Number of caught or uncaught exceptions during the session. High exception counts indicate error-prone code paths even when the app didn't fully crash.
Timestamp time.Time — When the crash or exception occurred. Helps correlate the event with a specific point in the user's session.
Type string — Exception or crash type (e.g., NullPointerException, OutOfMemoryError). Identifies the category of failure.
Message string — The exception message text. Provides context about what specifically went wrong.
Location string — The class 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 (ulimit). If OpenFDs approaches this, 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 open. High values can 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 file descriptor leak that will eventually crash the app.

GfxInfo Detailed Metrics

Field Type Unit Description
Frames0to16ms int count Frames rendered in 0–16ms — these are good, on-time frames the user experiences as smooth.
Frames16to32ms int count Frames that took 16–32ms — slightly slow, causing minor stutter that 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 counted 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 — the slowest 1% of frames. Represents the worst-case rendering experience.
DrawTimeMs float64 ms Time spent issuing draw commands to the GPU.
SyncTimeMs float64 ms Time spent waiting for the 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 swap the front and back rendering buffers to display the frame.
JankyFrames int count Total count of janky frames (>16.67ms) in the sample. Directly measures rendering quality from the user's perspective.
JankyFramePercent float64 % Percentage of all frames that were janky. A value above 10% is generally noticeable as an unsmooth experience.

Wake Lock Metrics

Field Type Unit Description
ActiveWakeLocks int count Number of wake locks currently held by the app. Wake locks prevent the device from sleeping — excess wake locks drain battery in the background.
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 Android Doze mode. Doze conserves battery by restricting background activity.
Tag string — The wake lock tag/name assigned by the app. Identifies which component in the app acquired the lock.
Type string — Wake lock type: partial, full, screen_dim, etc. Describes what the wake lock is preventing the device from doing.
DurationMs int64 ms Duration a specific wake lock instance was held. Helps identify which specific lock is causing battery issues.
Package string — The package name 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 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.
TotalQueryTimeMs float64 ms Total time spent in database queries during the session. Reflects cumulative database load.
DatabaseSizeKB int64 KB The size of the SQLite database file on disk. Unexpectedly large databases can slow 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.
Timestamp time.Time — When the slow query was captured. 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.
WifiRSSI int dBm Wi-Fi signal strength in dBm — more negative means weaker signal (e.g., -50 is strong, -85 is weak).
WifiLinkSpeed int Mbps Wi-Fi link speed negotiated between the device and the access point. Low link speeds limit download/upload 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.
DNSLookupMs float64 ms Time to resolve a hostname to an IP address. High values indicate DNS server issues that delay every network request.
TCPConnectMs float64 ms Time to establish a TCP connection to a server. Reflects network latency between the device and the server.
TLSHandshakeMs float64 ms Time to complete the TLS/SSL security handshake. Adds to the total connection setup time before any data is transferred.
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 speed is acceptable.

Launch Timing Metrics

Field Type Unit Description
ColdStartMs int64 ms Time for the app to launch from a completely closed state (no cached process). This is the slowest launch type and represents the worst-case startup the user experiences.
WarmStartMs int64 ms Time to launch when the app process exists in memory but the Activity was destroyed. Faster than cold start as the app process doesn't need to be created from scratch.
HotStartMs int64 ms Time to bring the app back to the foreground from a backgrounded state. The fastest launch type — the Activity already exists in memory.
DisplayedMs int64 ms Time from launch until the first frame is displayed to the user (Time to Initial Display). This is what the user perceives as the app's load time.

Page Transition Metrics

Field Type Unit Description
Timestamp time.Time — When the screen transition occurred during the session.
FromActivity string — The Activity/screen the user was navigating away from.
ToActivity string — The Activity/screen the user was navigating to.
Package string — The app package name involved in the transition.
DurationMs int64 ms Time for the transition to complete — from the user's tap to the new screen being displayed (TTID).
FullyDrawnMs int64 ms Time until the screen is fully populated with content (TTFD). A screen may display its skeleton/shell quickly but take longer to load actual data.
AvgTransitionMs float64 ms Average transition time across all screen changes in the session. Indicates overall navigation responsiveness.
MaxTransitionMs int64 ms The slowest single screen transition observed. Pinpoints the worst navigation experience in the session.
SlowTransitions int count Number of transitions that exceeded 500ms. Each slow transition is a moment the user waited visibly for a screen to appear.

Jank Metrics

Field Type Unit Description
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 to the app.
SlowDeliveryCount int count Count of slow delivery events — times when delivering input to the app took longer than expected.
Timestamp time.Time — When the jank event occurred during the session.
Type string — Jank event type: slow_frame, skipped_frames, or slow_dispatch.
FramesOrMs int64 count/ms For skipped_frames events: the number of frames skipped. For slow_frame events: the duration in ms the frame took.
Activity string — The active Activity/screen when the jank was recorded. Helps identify which screen is causing rendering issues.

Device Info

Field Type Unit Description
ID string — ADB device serial number — the unique identifier for this physical device.
Name string — Human-readable device name as set by the user or manufacturer.
Platform string — Always "android" for Android devices.
Brand string — Device brand (e.g., Samsung, Google, OnePlus).
Model string — Device model name (e.g., Galaxy S23, Pixel 7).
Manufacturer string — Device manufacturer name.
OSVersion string — Android OS version string (e.g., "14"). Helps correlate issues with specific Android versions.
SDKVersion int — Android SDK API level (e.g., 34 for Android 14). 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.

App Info

Field Type Unit Description
PackageName string — The app's package name (e.g., com.example.app). Uniquely identifies the app on the device.
AppName string — The app's display name as shown to the user.
Version string — The version name string (e.g., "5.2.1") — the human-readable version shown in app stores.
VersionCode int — The integer build version code. Used internally to distinguish builds when the version name is the same.
UID int — Linux user ID assigned to the app by the OS. Used for system-level permission and resource attribution.

Per-Screen (Activity) Metrics

Field Type Unit Description
Name string — The Activity 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 optimising.
AvgLoadTimeMs float64 ms Average time-to-interactive for this screen across all visits. Reflects typical user wait time when navigating to this screen.
MaxLoadTimeMs int64 ms The slowest observed load time for this screen. Captures worst-case user experience on this screen.
JankEventCount int count Number of jank 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 ANR events 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.
AvgCPU float64 % Average CPU usage while this screen was active. High values explain battery drain or thermal issues on specific screens.
AvgMemoryMB float64 MB Average memory usage while this screen was active. Helps identify memory-heavy screens.
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 ANR 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 issues.
Level string — Score tier: "good", "moderate", or "poor". The quickest signal of whether this screen is performing acceptably.