> For the complete documentation index, see [llms.txt](https://docs.qapilot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qapilot.io/detailed-documentation/test-plan-executions/device-metrics.md).

# Device Metrics

## Overview

Device Metrics gives real-time performance observability layer inside every test execution report. When enabled, it appears as a dedicated **Device Metrics** tab alongside the standard report tabs.

The tab captures hardware and runtime telemetry directly from the device during execution - CPU, memory, battery, network, and rendering performance, and surfaces it as threshold alerts, trend charts, and a step-by-step breakdown. This makes it possible to spot performance regressions, correlate spikes with specific test steps, and track app health across test plan runs without leaving the report.

> **Note:** Device Metrics is currently supported for **Android** only.

***

## Enabling Device Metrics

Device Metrics is off by default. To enable it for a test plan:

1. Open the test plan configuration
2. In the execution settings, Toggle **App Performance Analysis** to enabled before launching the run.

Once enabled, the **Device Metrics** tab appears in all subsequent execution reports for that test plan.

***

## Performance Thresholds

At the top of the Device Metrics tab, a row of metric cards summarises the peak and average readings recorded during the execution.

<figure><img src="/files/PRBbzvCcSy5NRKNhWxTK" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="176.5546875">Metric</th><th>What It Shows</th></tr></thead><tbody><tr><td><strong>Peak System CPU</strong></td><td>Highest system-wide CPU usage observed, with the session average</td></tr><tr><td><strong>Peak Memory</strong></td><td>Highest app memory consumption (MB), with the session average</td></tr><tr><td><strong>Bottom (Battery)</strong></td><td>Battery drain recorded; shows drain percentage and scale</td></tr><tr><td><strong>Peak Network</strong></td><td>Highest network throughput observed; includes cumulative Rx and Tx values</td></tr><tr><td><strong>Peak Janky Frames</strong></td><td>Highest janky frame percentage recorded, with the total jank frame count average</td></tr></tbody></table>

These cards give you a health summary before you dive into the detailed alert and chart sections below.

### Benchmarks

Benchmarks define the thresholds that determine when an alert fires and at what severity level.

Benchmarks apply across every test plan. You can customise the default thresholds to match your app's specific performance targets.

***

## Alert Summary

The **Alert Summary** section reports the total number of threshold breaches detected across the entire execution, grouped by severity:

<table><thead><tr><th width="137.61328125">Severity</th><th width="132.734375">Colour</th><th>Meaning</th></tr></thead><tbody><tr><td><strong>Critical</strong></td><td>Red</td><td>Threshold exceeded significantly; likely to affect user experience or stability</td></tr><tr><td><strong>Warning</strong></td><td>Yellow</td><td>Threshold exceeded moderately; worth investigating</td></tr><tr><td><strong>Info</strong></td><td>Blue/Grey</td><td>Threshold reached within an acceptable range; flagged for awareness</td></tr></tbody></table>

Each breach is displayed as an expandable alert card below the summary counts.

#### Alert Cards

Every alert card includes a description of the breach, the measured value, and the threshold it violated. Example alerts include:

* **High app CPU detected** - App CPU reached or exceeded the critical threshold in a measured percentage of samples. Shows peak app CPU, average app CPU, and overage percentage.
* **Elevated system CPU detected** - System CPU was between defined warning and critical bands across a percentage of measured steps.
* **App startup time above 3s** - Application reached its fully drawn state in more than 3 seconds, indicating heavy initialisation work on the main thread or slow runtime at startup.
* **Moderate system CPU detected** - System CPU was between warning bands across a percentage of measured steps; shows highest observed and average values.
* **Moderate app CPU detected** - App CPU was between moderate thresholds across measured samples.
* **Moderate app memory usage detected -** Memory consumption reached a moderate threshold during execution.

***

## Visualize Metrics

The Visualize Metrics section renders time-series charts for each telemetry signal collected during the run. Use the tab bar to switch between signals:

<table><thead><tr><th width="156.17578125">Tab</th><th>Signal</th></tr></thead><tbody><tr><td><strong>CPU</strong></td><td>App CPU and System CPU usage over time</td></tr><tr><td><strong>Memory</strong></td><td>App memory consumption (MB) over time</td></tr><tr><td><strong>Janky Frames</strong></td><td>Janky frame percentage per interval</td></tr><tr><td><strong>Battery</strong></td><td>Battery drain over time</td></tr><tr><td><strong>Network</strong></td><td>Network download and upload throughput over time</td></tr></tbody></table>

Each chart plots the metric against the execution timeline. Hover over any data point to see the exact value and timestamp.

> **Janky Frames note:** The chart shows **Janky Frame %** (frames that missed their render deadline as a percentage of total frames), giving a more meaningful signal than raw frame counts.

<figure><img src="/files/r77mmEp3BT9QbHlTgnEY" alt=""><figcaption></figcaption></figure>

#### Correlating Signals

Signals in different tabs can be related. Some common correlations to look for:

* High network download activity often coincides with spikes in System CPU usage
* High System CPU usage can accelerate battery drain
* High FPS rendering load (janky frames) can contribute to elevated App CPU

Use the timeline as a shared axis - a spike in one chart at a given timestamp maps directly to the same point in other charts.

***

### Step Details

The **Step Details** panel on the right side of the Device Metrics tab ties the performance data back to individual test steps. As you review the charts, the panel shows a device screenshot corresponding to the selected point in the execution, so you can see exactly what was happening on screen when a metric spike or threshold breach occurred.

This makes it straightforward to identify which test step or user interaction triggered a performance issue.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.qapilot.io/detailed-documentation/test-plan-executions/device-metrics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.