For Developers‎ > ‎

Telemetry: Introduction

Get Telemetry!

Telemetry 101

Telemetry is Chrome's performance testing framework. It allows you to perform arbitrary actions on a set of web pages and report metrics about it. The framework abstracts:

  • Launching a browser with arbitrary flags on any platform.
  • Opening a tab and navigating to the page under test.
  • Fetching data via the Inspector timeline and traces.
  • Using Web Page Replay to cache real-world websites so they don’t change when used in benchmarks.

Design Principles

  • Write one performance test that runs on all platforms - Windows, Mac, Linux, Chrome OS, and Android for both Chrome and ContentShell.

  • Runs on browser binaries, without a full Chromium checkout, and without having to build the browser yourself.

  • Use WebPageReplay to get repeatable test results.

  • Clean architecture for writing benchmarks that keeps measurements and use cases separate.

  • Run on non-Chrome browsers for comparative studies (not yet implemented).

Should my test use Telemetry?

It depends, what are you trying to measure? Are you trying to verify correctness?  If yes, Telemetry is not for you, but browser tests are your friend.

Telemetry is designed for performance tests that:

  • Can be written with pure JS/HTML/CSS.

  • Use real world content (rather than synthetic).

In addition, to check in a benchmarks to src/tools/perf/, we require that your benchmarks satisfy the requirements in Benchmark Policy document.

Code Concepts

Telemetry is a Python wrapper around Chrome's DevTools Remote Debugging Protocol.

The Telemetry framework lives in src/tools/telemetry/ and performance benchmarks live in src/tools/perf/.


Telemetry has an opinionated definition of a benchmark. A benchmark is a wrapper that encapsulates a measurement, a page set, and a set of optional browser options. You can run a benchmark with a short, simple command, and the test configuration is baked into the benchmark to ensure its consistency across machines.


A measurement (called PageTest in the code) is "something that can be run on a page." Given a page, a measurement evaluates the page’s performance. It can report many results, including numbers, histograms, traces, or pass/fail.

Page Set

A page set is a collection of URLs, which can be live sites, WebPageReplay archives, or local HTML files. Pages also have actions associated with them, such as clicking a button, scrolling the page, or performing a swipe gesture.

Next Steps

Contact Us or Follow Along

If you have questions, please email

You can keep up with Telemetry related discussions and code reviews by joining the telemetry group.

For more details: see us at our office (for Googlers). Non-googlers, please contact to set up a meeting.

Frequently Asked Questions

I get an error when I try to use recorded page sets.

The recordings are not included in the Chromium source tree. If you are a Google partner, run gsutil config to authenticate, then try running the test again. If you don't have gsutil installed on your machine, you can find it in src/tools/telemetry/third_party/gsutil/gsutil.

If you are not a Google partner, you can run on live sites with --use-live-sites or record your own page set archive.

I get mysterious errors about device_forwarder failing.

Your forwarder binary may be outdated. If you have built the forwarder in src/out that one will be used; if there isn't anything there Telemetry will default to downloading a pre-built binary. Try re-building the forwarder, or alternatively wiping the contents of src/out/ and running run_benchmark, which should download the latest binary.

I'm having problems with keychain prompts on Mac. Please help!

Make sure that your keychain is correctly configured.