heroku-nodejs-plugin v0.1.3

heroku-nodejs-plugin

A metrics plugin to add Heroku runtime metrics to an existing Node.js application. The plugin is added to a vendor directory in https://github.com/heroku/heroku-buildpack-nodejs.

How does it work?

You can see most of the implementation details in src/nativeStats.cc. The plugin sets callbacks around GC invocations, and during the prepare and check phases of the event loop, tracks the amount of time spent in each.

This data is exposed to a JS loop that periodically sends data to Heroku's metrics service.

Debugging

If the plugin is not working for you once you have enabled the feature on Heroku, the first thing you should do is set the ENV var NODE_DEBUG to heroku. By default all logging from the plugin is silenced.

$ heroku config:set NODE_DEBUG=heroku -a $APP_NAME

Metrics collected

{
  "counters": {
    "node.gc.collections": 748,
    "node.gc.pause.ns": 92179835,
    "node.gc.old.collections": 2,
    "node.gc.old.pause.ns": 671054,
    "node.gc.young.collections": 746,
    "node.gc.young.pause.ns": 91508781
  },
  "gauges": {
    "node.eventloop.usage.percent": 0.12,
    "node.eventloop.delay.ms.median": 5,
    "node.eventloop.delay.ms.p95": 100,
    "node.eventloop.delay.ms.p99": 100,
    "node.eventloop.delay.ms.max": 100
  }
}

Development

You can collect and print out metrics locally by running the included Go server:

$ PORT=5001 go run fake_metrics_server.go

You can run develop this locally by running build:

$ npm run build

and including the built module in another local Node app like:

$ NODE_OPTIONS="--require {{ working directory }}/heroku-nodejs-plugin/heroku-nodejs-plugin" HEROKU_METRICS_URL="http://localhost:5001" node src/index.js

Example app with periodic event loop and gc activity: https://github.com/heroku/node-metrics-single-process

Publishing new versions

New versions can be published to Github releases by merging all changes to main and running scripts/publish.sh