Perf Timeline CLI

A command line interface for generating Chrome Performance timelines.

!GitHub package version
!Dependencies
!Dev Dependencies

_Proudly built by:_

Demo

Generate a timeline, see how many Layout
events occurred, and get the total JavaScript execution time using Big Rig.

!Command line demo SVG

Motivations

Chrome DevTools' Performance panel is an industry standard for creating page load timelines to
understand how a website renders. As nice as it is to be able to click a few buttons to generate a
timeline, creating a Performance timeline from the command line extends the functionality to fit
different workflows.

Prior to building this tool, I struggled with a few issues when generating timelines from the Chrome
DevTools Performance panel.

1. The UI is sometimes slow and unresponsive, especially when debugging sites with high CPU usage.
1. Due to the way that some sites are constructed, it is hard to get a "clean" timeline. If you load
a page, then hit the "Start profiling and reload page" button, your timeline often includes trace
events for the unloading of the current page.
1. It is not possible to programmatically generate timelines. For instance, when trying to find a
performance regression, you may want to generate a timeline for the last 10 builds of a project.
This task requires a lot of extra UI steps within DevTools.

Perf Timeline attempts to improve the developer experience by providing a fast interface to generate
clean Performance timelines.

Prerequisites

Perf Timeline CLI requires Node 8+ and a current version of Chrome to view generated timelines.

Install

``
npm install -g @condenast/perf-timeline-cli
`

Usage

Generate a Performance timeline using defaults

`
perf-timeline generate https://www.wired.com
`

Generate a Performance timeline while throttling network

`
perf-timeline generate https://www.wired.com \
--emulate-network-conditions \
--latency 150 \
--upload-throughput 0.75 \
--download--throughput 1.6
`

Generate a Performance timeline while throttling CPU

`
perf-timeline generate https://www.wired.com \
--set-cpu-throttling-rate \
--rate 4
`

Generate a Performance timeline with screenshots

`
perf-timeline generate https://www.wired.com \
--screenshots
`

Generate a Performance timeline and save to a custom location

`
perf-timeline generate https://www.wired.com \
--path ~/my-timeline.json
`

Commands

generate

generate creates a Performance timeline for the URL passed to the command. The timeline is saved
as trace.json in the current directory. The timeline conditions can be adjusted using the
arguments documented below.

$3

* url (required; no default) - URL used to generate the Performance timeline

$3

Launch options are passed to the puppeteer.launch() command. Not all options are currently
supported. Supported options are listed below. For more information, please see the Puppeteer
Documentation.

* --ignore-https-errors (optional; false) - When --ignore-https-errors is passed, an HTTPS
errors will be ignored. This causes Chrome's default error behaviors when encountering HTTPS issues
to be ignored.
* --headless (options; true) - By default, Perf Timeline CLI runs in "headless" mode (i.e., without a visible
browser UI). To see a browser UI when generating the timeline, pass the --headless false to the
generate command. Please note that --no-headless is a synonym for --headless false.

$3

The Network Emulation Options allow you to generate a Performance timeline under specified network
conditions. To turn on network emulation, you must pass the --emulate-network-conditions flag
along with additional configuration options. These options mirror Chrome Headless' emulateNetworkConditions arguments.
All options are supported. Note that some arguments have been augmented for the CLI use case to
improve the product experience (e.g., throughout arguments us megabits per second instead of bytes
per second).

* --emulate-network-conditions (optional; false) - In order to set network conditions for a
timeline generation session, you must pass the --emulate-network-conditions flag. This flag
allows the other Network Emulation Options to be respected. They will be completely ignored unless
this flag is set.
* --offline (optional; false) - Passing the --offline flag to the generate command emulate
a network disconnect.
* --latency (optional; 0) - Artificial, minimum latency between request sent and response header
received expressed in milliseconds (ms).
* --download-throughput (optional: -1) - The maximum download speed in megabits per second. Note
Chrome Headless' version of this argument uses bytes per second. Perf Timeline CLI uses megabits per
second as that is a more common measure of network throughput. -1 disables throttling.
* --upload-throughput (optional: -1) - The maximum upload speed in megabits per second. Note
Chrome Headless' version of this argument uses bytes per second. Perf Timeline CLI uses megabits per
second as that is a more common measure of network throughput.-1 disables throttling.
* --connection-type (optional: none) - A label of the supposed underlying network connection
type that the browser is using. Supported values are documented under Chrome Headless'
ConnectType documentation.

$3

The Set CPU Throttling Rate Emulation Options allow you to generate a Performance timeline under
specified CPU conditions. To turn on CPU emulation, you must pass the --set-cpu-throttling-rate
flag along with additional configuration options. These options mirror Chrome Headless'
setCPUThrottlingRate arguments.
All options are supported.

* --set-cpu-throttling-rate (optional; false) - In order to set network conditions for a
timeline generation session, you must pass the --set-cpu-throttling-rate flag. This flag
allows the other Set CPU Throttling Rate Options to be respected. They will be completely ignored
unless this flag is set.
* --rate (optional; 1) - Sets the CPU throttling rate. The number represents the slowdown
factor (e.g., 2 is a "2x" slowdown).

$3

The Goto Options mirror the page.goto() method's options from Puppeteer. These options allow you
to configure how the page navigation is handled. All options are currently supported. Note that the
url option for page.goto is provided by the url, positional argument passed to generate. You
cannot override that option here. See the page.goto documentation for more
details.

* --timeout (optional; 30) - Maximum time in seconds to load the page until the timeline
generation is stopped. Note that if you emulate the network or CPU, or if you set later
--wait-until values, you should increase --timeout to improve the chances of successfully
generating a timeline.
* --wait-until (optional; load) - The success event for the navigation. Puppeteer "waits until"
this event has occurred to finish the timeline. load, domcontentloaded, networkidle0, and
networkidle2 are supported. Note that --timeout takes precedence over --wait-until. If the
--wait-until event has not occurred before the --timeout time is reached, an error is thrown and
no timeline will be generated.

$3

The Tracing Options allow to you configure the options for Puppeteer's page.tracing.start()
method. All options are supported. See the page.tracing.start documentation for more
details.

* --path (optional; ./trace.json) - The file path for where to save the trace.
* --screenshots (optional; false) - Passing the --screenshots flag causes Chrome to take
screenshots of the page as the timeline is generated. These screenshots are embedded in the tracing
file and are shown in DevTools when viewing the Performance timeline.
* --categories (optional; []) - The list of trace event categories to capture in the timeline.
This argument is passed as a comma separated list of categories. This option is useful if you wish
to reduce the overall size of the trace file. Note that limiting to certain categories only can
leave you with a timeline that does not appear to show anything when viewing in DevTools'
Performance panel. The best way to see the possible categories is to view a raw trace and look for
the cat` value of events.

Thanks

This project is built on the shoulders of giants. It's nothing more than a convenience wrapper
around some really exciting projects, including:

* Puppeteer
* Chrome Headless
* Chrome DevTools
* Yargs

Contributors

See the list of contributors who
participated in writing this tool.