instrumental-agent

Instrumental Node.js Agent

Instrumental is an application monitoring platform built for developers who want a better understanding of their production software. Powerful tools, like the Instrumental Query Language, combined with an exploration-focused interface allow you to get real answers to complex questions, in real-time.

This agent supports custom metric monitoring for Node.js applications. It provides high-data reliability at high scale, without ever blocking your process or causing an exception.

Installation

npm install instrumental-agent

Package details on npmjs.com

Usage

You will need to set the API token. API tokens can be found in the project tokens documentation or in your user settings page. Use the 'enabled' flag to control if the agent actually reports. This is useful for not reporting in dev/test/staging/etc. environments.

Configuration

var I = require('instrumental-agent');
I.configure({
  // from here: https://instrumentalapp.com/docs/tokens
  apiKey:  'project_token',
 
  // optional, default shown
  host:    'collector.instrumentalapp.com',
 
  // optional, default shown
  enabled: true,
 
  // optional, default is undefined, connection timeout in ms
  timeout: 10000,
});

increment

I.increment('metric.name' /*, value = 1, time = now, count = 1 */);

gauge

I.gauge('metric.name', 82.12 /*, time = now, count = 1 */);

notice

I.notice('An event occurred' /*, time = now, duration = 0 */);

Special (dis)connection handling

If you need to control the point at which the Agent disconnects from the Instrumental metric collectors, you can manually call disconnect().

var I = require('instrumental-agent');
I.configure({ /* things */ });
/* do some work and record metrics */
I.disconnect();

Contributing

Make a PR! Say roughly what you've changed, why you did so, and any ancillary data you have like gotchas, issues you suspect, awesomeness, etc.

Run the Tests and other Helpers

> npm install
> npm test # this should be all green
> npm run coverage # this should probably be like… as good as when you started
> npm run jshint # ??? I guess no errors? not sure what this does

Releasing

1. Sign up for npmjs.com
2. Pull latest master
3. Merge feature branch(es) into master
4. npm test
5. Increment version in repo

• package.json

1. Update CHANGELOG.md
2. Commit "Release version vX.Y.Z"
3. Push to GitHub
4. npm publish
5. Tag version: git tag 'vX.Y.Z' && git push --tags
6. Verify update on https://www.npmjs.com/package/instrumental-agent
7. Refresh documentation on instrumentalapp.com

Cool Contributors 😎

• @spacetc62
• @gmcnaught
• @janxious
• @jqr
• @jason-o-matic
• @JamesPaden
• @pmidge
• @acanimal
• @alecgorge