latency-monitor

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).

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:

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):

<script src='//cdn.jsdelivr.net/latency-monitor/0.2.1/EventLoopPrinterWebpacked.js'></script>

Load via script in JavaScript (paste in your devtools - e.g. Chrome DevTools):

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):

$.getScript('//cdn.jsdelivr.net/latency-monitor/0.2.1/EventLoopPrinterWebpacked.js');

Last resort: Load via XMLHTTPRequest:

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