latency-monitor

[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage Status][coveralls-image]][coveralls-url] [![Dependency Status][depstat-image]][depstat-url]

> A monitor that periodically times how long it takes for a callback to be called. Think event loop latency.

Usage

This tool allows you to time and get summaries of how long async functions took. By default, it assumes you want to measure
event loop latency, but as this example shows,
you can use it for a simple ping pong setup with Promises too. This code works in both browsers and node.js and will do its best effort to use as accurate a timer as possible.

Example event loop monitor (default).
``javascript
import LatencyMonitor from 'latency-monitor';

const monitor = new LatencyMonitor();
console.log('Event Loop Latency Monitor Loaded: %O', {
latencyCheckIntervalMs: monitor.latencyCheckIntervalMs,
dataEmitIntervalMs: monitor.dataEmitIntervalMs
});
monitor.on('data', (summary) => console.log('Event Loop Latency: %O', summary));
/*
* In console you will see something like this:
* Event Loop Latency Monitor Loaded:
* {dataEmitIntervalMs: 5000, latencyCheckIntervalMs: 500}
* Event Loop Latency:
* {avgMs: 3, events: 10, maxMs: 5, minMs: 1, lengthMs: 5000}
*/
`



More Theory


We use setTimeout to pick when to run the next test. We do this so we can add in some randomness to avoid aligning
our events with some external event (e.g. another timer that triggers a slow event). When we are monitoring event loop latency
(i.e. no async function provided), then we simply record how long getting the callback really took.
When we measure an async function, we only time how long that async function took to call the passed in cb.

When used in a browser, this tool disables itself if the page is hidden because of restrictions with how often we can
call setTimeout see this.

When monitoring event loop latency, we add in 1ms to all measurements. setTimeout is not more accurate than 1ms, so this ensures
every number is greater than 0. To remove this offset, simply subtract 1 from all stats.
TLDR; event loop latency monitoring does NOT have sub-millisecond accuracy, even if the emitted numbers show this.

Installation

Install latency-monitor as a dependency:

`shell
npm install --save latency-monitor
`

On Demand Browser Latency

We also host a copy of the browser event loop latency detector on jsdelivr.
To use this, you can include the script in a src tag, or simply load it in Chrome DevTools. You should expect to see
the same output as documented above in usage.

Load via script element (paste into page's html):
`html

`

Load via script in JavaScript (paste in your devtools - e.g. Chrome DevTools):
`javascript
var el = document.createElement('script');
el.setAttribute('src', 'https://cdn.jsdelivr.net/latency-monitor/0.2.1/EventLoopPrinterWebpacked.js')
document.body.appendChild(el)
`

Load via jquery (if you have $ loaded on the page already, paste this in Chrome DevTools or in your code):
`javascript
$.getScript('//cdn.jsdelivr.net/latency-monitor/0.2.1/EventLoopPrinterWebpacked.js');
`

Last resort: Load via XMLHTTPRequest:
`javascript
var xhr = new XMLHttpRequest();
xhr.open("GET", "//cdn.jsdelivr.net/latency-monitor/0.2.1/EventLoopPrinterWebpacked.js", true);
xhr.onreadystatechange = function() {
if (xhr.readyState == 4) {
// WARNING! Might be evaluating an evil script!
var resp = eval(xhr.responseText);
}
};
xhr.send();
`
Note: Remember to change 0.2.1 above to whatever is the latest version of latency-monitor.

Debugging


We use debug. In node set env variable DEBUG=latency-monitor:*
or in a browser localStorage.debug='latency-monitor'` to see debugging output.

Notes

This is a reasonable attempt to make a latency monitor. There are issues such as:
- We don't wait for the last event to finish when emitting stats. This means if the last event in a cycle takes the longest,
or is never returned, then for that cycle large latency isn't recorded.

License
-------------
Apache-2.0 License

[npm-url]: https://npmjs.org/package/latency-monitor
[npm-image]: https://badge.fury.io/js/latency-monitor.svg

[travis-url]: http://travis-ci.org/mlucool/latency-monitor
[travis-image]: https://secure.travis-ci.org/mlucool/latency-monitor.png?branch=master

[coveralls-url]: https://coveralls.io/github/mlucool/latency-monitor?branch=master
[coveralls-image]: https://coveralls.io/repos/mlucool/latency-monitor/badge.svg?branch=master&service=github

[depstat-url]: https://david-dm.org/mlucool/latency-monitor
[depstat-image]: https://david-dm.org/mlucool/latency-monitor.png