1# Power Telemetry tests
2
3[TOC]
4
5## Overview
6
7The Telemetry power benchmarks measure power indirectly by measuring the CPU time used by Chrome while it performs various tasks (a.k.a. user stories).
8
9## List of power metrics
10
11### `cpu_time_percentage_avg`
12This metric measures the average number of cores that Chrome used over the duration of the trace.
13
14This metric is enabled by adding `'cpuTimeMetric'` to the list of TBM2 metrics in the benchmark's Python class:
15
16```python
17options.SetTimelineBasedMetrics(['cpuTimeMetric', 'memoryMetric'])
18```
19
20Additionally, the `toplevel` trace category must be enabled for this metric to function correctly because it ensures that a trace span is active whenever Chrome is doing work:
21
22```python
23category_filter = chrome_trace_category_filter.ChromeTraceCategoryFilter(filter_string='toplevel')
24```
25
26## List of power benchmarks
27
28The primary power benchmarks are:
29
30- **`system_health.common_desktop`**: A desktop-only benchmark in which each page focuses on a single, common way in which users use Chrome (e.g. browsing Facebook photos, shopping on Amazon, searching Google)
31- **`system_health.common_mobile`**: A mobile-only benchmark that parallels `system_health.common_desktop`
32- **`power.desktop`**: A desktop-only benchmark made up of two types of pages:
33  - Pages focusing on a single, extremely simple behavior (e.g. a blinking cursor, a CSS blur animation)
34  - Pages on which Chrome has exhibited pathological idle behavior in the past
35- **`media.desktop`**: A desktop-only benchmark in which each page tests a particular media-related scenario (e.g. playing a 1080p, H264 video with sound)
36- **`media.mobile`**: A mobile-only benchmark that parallels `media.desktop`
37
38[This spreadsheet](https://docs.google.com/spreadsheets/d/1xaAo0_SU3iDfGdqDJZX_jRV0QtkufwHUKH3kQKF3YQs/edit#gid=0) lists the owner for each benchmark.
39
40## Adding new power test cases
41To add a new test case to a power benchmark, contact the owner of the benchmark above that sounds like the best fit.
42
43## Running the benchmarks locally
44See [this page](https://github.com/catapult-project/catapult/blob/master/telemetry/docs/run_benchmarks_locally.md) for instructions on how to run the benchmarks locally.
45
46## Seeing power benchmark results
47Enter the platform, benchmark, and metric you care about on [this page](https://chromeperf.appspot.com/report) to see how the power metrics have moved over time.
48