Buffered metrics reporting via the DataDog HTTP API
npm install @joakimbeng/datadog-metrics> Buffered metrics reporting via the DataDog HTTP API.
[![NPM Version][npm-image]][npm-url]
[![Build Status][travis-image]][travis-url]
[![Downloads Stats][npm-downloads]][npm-url]
Datadog-metrics lets you collect application metrics through DataDog's HTTP API. Using the HTTP API has the benefit that you don't need to install the DataDog Agent (StatsD). Just get an API key, install the module and you're ready to go.
The downside of using the HTTP API is that it can negatively affect your app's performance. Datadog-metrics solves this issue by buffering metrics locally and periodically flushing them to DataDog.
``sh`
npm install @joakimbeng/datadog-metrics
Save the following into a file named example_app.js:
`js
const metrics = require('datadog-metrics');
metrics.init({host: 'myhost', prefix: 'myapp.'});
function collectMemoryStats() {
var memUsage = process.memoryUsage();
metrics.gauge('memory.rss', memUsage.rss);
metrics.gauge('memory.heapTotal', memUsage.heapTotal);
metrics.gauge('memory.heapUsed', memUsage.heapUsed);
}
setInterval(collectMemoryStats, 5000);
`
Run it:
`sh`
DATADOG_API_KEY=YOUR_KEY DEBUG=metrics node example_app.js
There's also a longer tutorial that walks you through setting up a monitoring dashboard on DataDog using datadog-metrics.
Make sure the DATADOG_API_KEY environment variable is set to your DataDogDATADOG_APP_KEY
API key. You can find the API key under Integrations > APIs. _You only need to provide the API key, not the APP key. However, you can provide an APP key if you want by setting the environment variable._
There are three ways to use this module to instrument an application.
They differ in the level of control that they provide.
#### Use case #1: Just let me track some metrics already!
Just require datadog-metrics and you're ready to go. After that you can call
gauge, increment and histogram to start reporting metrics.
`js`
var metrics = require('datadog-metrics');
metrics.gauge('mygauge', 42);
#### Use case #2: I want some control over this thing!
If you want more control you can configure the module with a call to init.gauge
Make sure you call this before you use the , increment and histogram
functions. See the documentation for below to learn more.
`js`
var metrics = require('datadog-metrics');
metrics.init({host: 'myhost', prefix: 'myapp.'});
metrics.gauge('mygauge', 42);
#### Use case #3: Must. Control. Everything.
If you need even more control you can create one or more BufferedMetricsLogger instances and manage them yourself:
`js`
var metrics = require('datadog-metrics');
var metricsLogger = new metrics.BufferedMetricsLogger({
api_key: 'TESTKEY',
api_host: 'app.datadoghq.eu',
host: 'myhost',
prefix: 'myapp.',
flushIntervalSeconds: 15,
defaultTags: ['env:staging', 'region:us-east-1']
});
metricsLogger.gauge('mygauge', 42);
metrics.init(options)
Where options is an object and can contain the following:
- host: Sets the hostname reported with each metric. (optional)prefix
- Setting a hostname is useful when you're running the same application
on multiple machines and you want to track them separately in DataDog.
- : Sets a default prefix for all metrics. (optional)flushIntervalSeconds
- Use this to namespace your metrics.
- : How often to send metrics to DataDog. (optional)flush()
- This defaults to 15 seconds. Set it to 0 to disable auto-flushing which
means you must call manually.api_key
- : Sets the DataDog API key. (optional)DATADOG_API_KEY
- It's usually best to keep this in an environment variable.
Datadog-metrics looks for the API key in by default.api_host
- : Sets the DataDog API host. (optional)app.datadoghq.com
- Defaults to
- : Sets the DataDog APP key. (optional)DATADOG_APP_KEY
- It's usually best to keep this in an environment variable.
Datadog-metrics looks for the APP key in by default.defaultTags
- : Default tags used for all metric reporting. (optional)agent
- Set tags that are common to all metrics.
- : custom https agent (optional)
Example:
`js`
metrics.init({host: 'myhost', prefix: 'myapp.'});
metrics.gauge(key, value[, tags[, timestamp]])
Record the current _value_ of a metric. They most recent value in
a given flush interval will be recorded. Optionally, specify a set of
tags to associate with the metric. This should be used for sum values
such as total hard disk space, process uptime, total number of active
users, or number of rows in a database table. The optional timestamp
is in milliseconds since 1 Jan 1970 00:00:00 UTC, e.g. from Date.now().
Example:
`js`
metrics.gauge('test.mem_free', 23);
metrics.increment(key[, value[, tags[, timestamp]]])
Increment the counter by the given _value_ (or 1 by default). Optionally,Date.now()
specify a list of _tags_ to associate with the metric. This is useful for
counting things such as incrementing a counter each time a page is requested.
The optional timestamp is in milliseconds since 1 Jan 1970 00:00:00 UTC,
e.g. from .
Example:
`js`
metrics.increment('test.requests_served');
metrics.increment('test.awesomeness_factor', 10);
metrics.histogram(key, value[, tags[, timestamp]])
Sample a histogram value. Histograms will produce metrics that
describe the distribution of the recorded values, namely the minimum,
maximum, average, count and the 75th, 85th, 95th and 99th percentiles.
Optionally, specify a list of _tags_ to associate with the metric.
The optional timestamp is in milliseconds since 1 Jan 1970 00:00:00 UTC,
e.g. from Date.now().
Example:
`js`
metrics.histogram('test.service_time', 0.248);
metrics.flush([onSuccess[, onError]])
Calling flush sends any buffered metrics to DataDog. Unless you setflushIntervalSeconds to 0 it won't be necessary to call this function.
It can be useful to trigger a manual flush by calling if you want to
make sure pending metrics have been sent before you quit the application
process, for example.
Datadog-metrics uses the debug
library for logging at runtime. You can enable debug logging by setting
the DEBUG environment variable when you run your app.
Example:
`sh`
DEBUG=metrics node app.js
`sh`
npm test
- 1.0.0
- FIX: add support for api_host option see dogapi
- FEAT: start rewriting using new syntax BREAKING CHANGE: requires NodeJS +v10
- FEAT: replace JSHint and JSCS with ESLint
- 0.8.1
- FIX: don't increment count when value is 0 (Thanks to @haspriyank)
- 0.8.0
- allow passing in custom https agent (Thanks to @flovilmart)
- 0.7.0
- update metric type counter to count as counter is deprecated by Datadog (Thanks to @dustingibbs)metrics.flush()
- 0.6.1
- FIX: bump debug to 3.1.0 to fix NSP Advisory #534 (Thanks to @kirkstrobeck)
- 0.6.0
- FIX: call onSuccess on flush even if buffer is empty (Thanks to @mousavian)
- 0.5.0
- ADD: ability to set custom timestamps (Thanks to @ronny)
- FIX: 0 as valid option for flushIntervalSeconds (thanks to @dkMorlok)
- 0.4.0
- ADD: Initialize with a default set of tags (thanks to @spence)
- 0.3.0
- FIX: Don't overwrite metrics with the same key but different tags when aggregating them (Thanks @akrylysov and @RavivIsraeli!)
- ADD: Add success/error callbacks to (Thanks @akrylysov!)setDefaultXYZ()
- ADD: Allow DataDog APP key to be configured (Thanks @gert-fresh!)
- Bump dependencies to latest
- Update docs
- 0.2.1
- Update docs (module code remains unchanged)
- 0.2.0
- API redesign
- Remove and added init()
- 0.1.1
- Allow to be called with a default value of 1counter
- 0.1.0
- The first proper release
- Rename to increment
- 0.0.0
- Work in progress
This module is heavily inspired by the Python dogapi module.
Daniel Bader – @dbader_org – mail@dbader.org
Distributed under the MIT license. See LICENSE` for more information.
https://github.com/dbader/node-datadog-metrics
[npm-image]: https://img.shields.io/npm/v/datadog-metrics.svg?style=flat-square
[npm-url]: https://npmjs.org/package/datadog-metrics
[npm-downloads]: https://img.shields.io/npm/dm/datadog-metrics.svg?style=flat-square
[travis-image]: https://img.shields.io/travis/dbader/node-datadog-metrics/master.svg?style=flat-square
[travis-url]: https://travis-ci.org/dbader/node-datadog-metrics