@nearform/stats
v1.0.1
Published
[![Build Status](https://travis-ci.org/nearform/stats.svg?branch=master)](https://travis-ci.org/nearform/stats)
Downloads
8
Readme
stats
Collect stats about your node.js process.
Intro to the nearform stats tooling
Created with the purpose to make creating visualisations about your process easy. At nearform, we achieve this using the modules stats stats-to-elasticsearch and create-stats-dashboard. This makes it very easy to collect process stats in elasticsearch and visualise them in a dashboard in kibana, similar to that below:
Once your dashboard is setup with create-stats-dashboard, all you should need to do is require the stats-to-elasticsearch module and point it at the dashboard to get cool (and useful) visualisations!
Installation
npm install --save @nearform/stats
Usage
This module exports a function which instantiates an event emitter which emits a single event, stats
. This event emitter has two functions which can be used to start and stop probing for statistics, start()
and stop()
. Listen to the stats
event to get useful process statistics.
Example:
const StatsProducer = require('@nearform/stats')
const statsProducer = new StatsProducer()
statsProducer.start()
statsProducer.on('stats', function (stats) {
// so something with these stats
})
// some time later...
statsProducer.stop()
API
StatsProducer(opts)
Returns an event emitter which emits a stats
event containing useful stats.
- opts: an
object
which can contain the following properties to set for generating statistics- sampleInterval: a
number
representing the amount of seconds to take a sample when running. Defaults to 5 seconds. - eventLoopSampleInterval: the interval at which the eventLoop should be sampled, defaults to 500.
- eventLoopLimit: the maximum amount of delay that is tolerated before overLimit is detected as true, defaults to 50.
- tags: an array of user defined strings to tag your stats with
- sampleInterval: a
The StatsProducer event emitter which is returned has the following methods.
statsProducer.start()
- starts the stats producer listening and producing stats.
statsProducer.stop()
- stops producing stats.
Stat object
The stat object which is emitted has the following properties:
tags
: the array of user defined strings defined in the constructor to tag your stats withid
: A uuid generated at start up for this stats producertimestamp
: The time the stats were generatedprocess
: an object with the following properties extracted from the global process object. See the official node documentation for more information on these properties.cpuUsage
: This is a function on the process object which is invoked to fill in the value.memoryUsage
: This is a function on the process object which is invoked to fill in the value.uptime
: This is a function on the process object which is invoked to fill in the value.title
pid
release
versions
argv
execArgv
execPath
system
: an object with the following properties extracted from the os module. See the official node documentation for more information on these properties.cpus
: This is a function on the os module which is invoked at initialisation to fill in the value. This is not expected to change.uptime
: This is a function on the os module which is invoked to fill in the value.freemem
: This is a function on the os module which is invoked to fill in the value.loadavg
: This is a function on the os module which is invoked to fill in the value.platform
arch
eventLoop
: this is an object which contains the following properties extracted from benchmarking the eventloop.delay
: The delay in milliseconds (and fractions) from the expected eventloop run. It might be negative (in older nodes).limit
: The maximum amount of delay that is tolerated before overLimit becomes true.overlimit
: true if the delay > limit.
gcRuns
: an array with objects added after every gc run. see here to see the format of the objects added
Useful links
- stats - makes generating the stats to be visualised a breeze!
- stats-to-elasticsearch - makes sending the stats to es a breeze!
- create-stats-dashboard - makes creating your kibana dashboard a breeze!
License
Apache 2.0