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