phantomas

GitHub Logo

PhantomJS-based modular web performance metrics collector. And why phantomas? Well, because :)

NPM version Build Status

Download stats

Requirements

Installation

npm install --global --no-optional phantomas phantomjs-prebuilt@^2.1.5

This will install the latest version of PhantomJS and add a symlink called phantomas (pointing to ./bin/phantomas.js) to your system’s PATH

You may need to install libfontconfig by running sudo apt-get install libfontconfig1.

Development version

To get the latest development version of phantomas (and install all required dependencies):

git clone git@github.com:macbre/phantomas.git
npm install

Having problems?

Please refer to /Troubleshooting.md

Libraries

phantomas is written in JavaScript, but you can experience it in different languages as well ;)

Python

Latest Version Supported Python versions

pip install phantomas

Features

Contributors

All the contributors

Usage

phantomas comes as both command line tool and CommonJS module (see API docs) that you can use in your nodejs projects.

Single run

phantomas https://github.com/macbre/phantomas --verbose

You can measure the performance of your site without requests to 3rd party domains (but allowing CDN that serves your static assets):

phantomas https://github.com/macbre/phantomas --verbose --no-externals --allow-domain .fastly.net

Parameters

Multiple runs

Simply provide --runs option:

phantomas https://github.com/macbre/phantomas --verbose --runs 5

Only plain (the default one) and json reporters are currently supported in multiple runs mode.

Metrics

Current number of metrics: 135

Units:

Requests monitor (core module)

Due to PhantomJS issue #10156 body size related metrics are not reliable

AJAX requests

Assets types

Due to PhantomJS issue #10156 body size related metrics are not reliable

Cache Hits

Metrics are calculated based on Age and X-Cache headers added by Varnish / Squid servers

Headers

Domains

Cookies

DOM complexity

Metrics listed below are generated after the full page load

DOM hidden content

DOM queries

DOM mutations

These metrics are only available when running phantomas using Gecko engine (--engine=gecko)

Event listeners

Window performance

Times below are relative to responseEnd entry in NavigationTiming (represented by timeToLastByte metric). See NavigationTiming spec for more information.

Repaints

These metrics are only available when running phantomas using Gecko engine (--engine=gecko)

Requests statistics

Time is total duration, from the start of the request to the receipt of the final byte in the response. Latency is the time to load the first byte in the response. https://developers.google.com/chrome-developer-tools/docs/network

Includes HTTP 200 responses only

Requests to

keepAlive

Monitors the use of Connection: close and Keep-Alive

localStorage

jQuery

Requires jQuery 1.8.0+

Static assets

Caching

Time to first asset

Redirects

JavaScript bottlenecks

JavaScript errors

Error message and backtrace will be emitted as offenders

JavaScript console and alert

Main request

Analyzes bits of data pertaining to the main request only

Document height

Lazy-loadable images

Optional metrics

The following metrics are emitted only when certain options are passed to phantomas

CSS metrics

This is an experimental feature. Use --analyze-css option to enable it.

Take a look at analyze-css README for the full list of metrics.

Reporters

phantomas provides a number of reporters that can format the run results and send them to various tools. Use --reporter (or -R shortcut) option to use one.

Formatters

Results can be emitted as TAP, CSV and JSON. plain format is most useful for human beings :)

Parameters

Formatters can be provided with colon separated list of options:

$ phantomas http://foo.net -R csv:no-header:timestamp

This will omit CSV headers row and add current timestamp as the first column, so you can append the results line to a growing file.

CSV
JSON
Plain
StatsD
TAP
StatsD

StatsD integration

Metrics from phantomas run can be sent directly to StatsD and then graphed using graphite, graphene or any other tool of your choice. For instance:

$ phantomas http://app.net/start -R statsd --statsd-host stats.app.net --statsd-port 8125 --statsd-prefix 'myApp.mainPage.'

or

$ phantomas http://app.net/start -R statsd:stats.app.net:8125:myApp.mainPage.

will sent metrics to StatsD running on stats.app.net:8125 and prefix them with ‘myApp.mainPage’.

3rd-party reporters

These need to be installed on demand as 3rd party npm packages

Engines

phantomas can be run using PhantomJS 2.1.x (WebKit-powered headless browser) or SlimerJS (Gecko-based non headless browser, run using xfvb).

PhantomJS 2.1.x is a default engine.

You can choose the engine by using either:

Please note that support for SlimerJS is experimental at this point.

PhantomJS

All required binaries have already been installed by npm. No extra work needed here :)

SlimerJS

In order to use SlimerJS install the following Debian/Ubuntu packages:

sudo aptitude install xvfb libasound2 libgtk2.0-0

You will also need to install the module:

npm install --global slimerjs@^0.906.1

For developers

Custom modules

You can load your own, custom phantomas modules using --include-dirs option:

phantomas --include-dirs /my/path/to/custom/modules/ --url http://example.com

/my/path/to/custom/modules/ directory should contain custom modules, each in its own directory, e.g. /my/path/to/custom/modules/fooBar/fooBar.js.

Let’s make Web a bit faster!

Slides

Blogosphere

Introductions to phantomas and use cases:

Videos

Utilities

Use grunt to automate daily dev tasks, including your’s application web performance, via these great tools: