simple stats server
dead-simple resource stats for Node.js servers
introduction
Sometimes all you need is the basic resource stats Node core exposes. But really you'd like it as a JSON endpoint. And maybe you want to be able to check that your database connection is healthy or count the number of requests you're getting. Just a few simple things, exposed as a REST endpoint.
getting started
Install it with NPM.
> npm install --save simple-stats-server
The easiest way to use the server is to mount the connect/express-style middleware:
sss = require 'simple-stats-server'stats = sss express = require 'express'app = express # serve the REST API from the /stats path appuse '/stats'stats applisten 3000
Now visit the stats endpoint.
> curl localhost:3000/stats {"cpu":[0.32],"memory":{"system...
Add some route counters and system checks.
# mount early appuse statscount 'requests'appuse '/api'statscount 'api calls' statscheck 'database connection' dbcheckConnection cb not err and isUp
documentation
REST api
The simple stats server REST API is simple. The only method supported
is GET. Get the URL /
to retrieve the entire data structure, or
drill down by appending keys as path levels. For instance, to get the
current process uptime, get /uptime/process
.
The data structure looks something like this:
Server api
sss()
The return value of the exported function is a simple-stats-server. It acts as connect/express style middleware, so just mount it directly in your app. In express style, mount it at a subdirectory:
sss = require 'simple-server-stats'stats = sssappuse '/stats'stats
stats.check(name, predicate)
Add a status check to the stats server. The name
is used for the
JSON representation as well as the URL. Spaces are replaced with
dashes and the whole thing is downcased. The function predicate
determines the current status. It can be written in one of two forms,
synchronous, which is nullary -> Boolean
, and asynchronous, which is
unary (cb) ->
. The latter form callsback with a truthy or falsy
value, where the former returns it.
# a basic alive check (this is what ping is) statscheck 'alive'-> yes # check the status of the database connection statscheck 'database' myDatabasecheckConnection cb not error and isAlive
stats.count(name)
Creates a simple counter and returns it. The name
is treated the
same as in check
above, downcased and space-to-dashed. The returned
counter has the signature (req, res, next) ->
, and will call next
if it's a function, so the counter can be used directly as middleware.
You can also use the counter anywhere else in your application that
you'd like to count events.
# mount this early to count all requests appuse statscount 'requests' # create a custom event counter recordEvent = statscount 'custom event'recordEventrecordEventrecordEvent
stats.get(path, cb)
If you don't have an express application to mount the middleware,
you can use the get
method to write your own middleware appropriate
to your server setup. Call this method to get the JSON for the REST
api. path
should be the relative path for the stats server (the
root /
will return the whole structure). The function cb
should
have the signature (err, result) ->
. If the path doesn't match
anything, err
is 404
.
stats.end()
The server will set up an interval timer to poll the cpu. Use this method to cancel that timer when shutting down the server.