datadog-metrics

Buffered metrics reporting via the Datadog HTTP API.

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.

Installation

Datadog-metrics is compatible with Node.js v12 and later. You can install it with NPM:

npm install datadog-metrics --save

Example

Save the following into a file named example_app.js:

var 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:

DATADOG_API_KEY=YOUR_KEY DEBUG=metrics node example_app.js

Tutorial

There's also a longer tutorial that walks you through setting up a monitoring dashboard on Datadog using datadog-metrics.

Usage

Datadog API key

Make sure the DATADOG_API_KEY or DD_API_KEY environment variable is set to your Datadog API key (you can also set it via the apiKey option in code). You can find the API key under Integrations > APIs. Please note the API key is different from an application key. For more details, see Datadog’s “API and Application Keys” docs.

Module setup

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.

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. Make sure you call this before you use the gauge, increment and histogram functions. See the documentation for init below to learn more.

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:

var metrics = require('datadog-metrics');
var metricsLogger = new metrics.BufferedMetricsLogger({
    site: 'datadoghq.eu',
    apiKey: 'TESTKEY',
    host: 'myhost',
    prefix: 'myapp.',
    flushIntervalSeconds: 15,
    defaultTags: ['env:staging', 'region:us-east-1'],
    onError (error) {
        console.error('There was an error auto-flushing metrics:', error);
    }
});
metricsLogger.gauge('mygauge', 42);

API

Initialization

metrics.init(options)

Where options is an object and can contain the following:

host: Sets the hostname reported with each metric. (optional)
- Setting a hostname is useful when you're running the same application on multiple machines and you want to track them separately in Datadog.
prefix: Sets a default prefix for all metrics. (optional)
- Use this to namespace your metrics.
flushIntervalSeconds: How often to send metrics to Datadog. (optional)
- This defaults to 15 seconds. Set it to 0 to disable auto-flushing (which means you must call flush() manually).
site: Sets the Datadog "site", or server where metrics are sent. (optional)
- Defaults to datadoghq.com.
- See more details on setting your site at: https://docs.datadoghq.com/getting_started/site/#access-the-datadog-site
- You can also set this via the DATADOG_SITE or DD_SITE environment variable.
- Ignored if you set the reporter option.
apiKey: Sets the Datadog API key. (optional)
- It's usually best to keep this in an environment variable. Datadog-metrics looks for the API key in the DATADOG_API_KEY or DD_API_KEY environment variable by default.
- You must either set this option or the environment variable. An API key is required to send metrics.
- Make sure not to confuse this with your application key! For more details, see: https://docs.datadoghq.com/account_management/api-app-keys/
- Ignored if you set the reporter option.
appKey: ⚠️ Deprecated. This does nothing and will be removed in an upcoming release.

Sets the Datadog application key. This is not actually needed for sending metrics or distributions, and you probably shouldn’t set it. Do not confuse this with your API key! For more, see: https://docs.datadoghq.com/account_management/api-app-keys/
defaultTags: Default tags used for all metric reporting. (optional)
- Set tags that are common to all metrics.
onError: A function to call when there are asynchronous errors seding buffered metrics to Datadog. It takes one argument (the error). (optional)
- If this option is not set, the error will be logged to stderr.
histogram: An object with default options for all histograms. This has the same properties as the options object on the histogram() method. Options specified when calling the method are layered on top of this object. (optional)
retries: How many times to retry failed metric submissions to Datadog’s API.
- Defaults to 2.
- Ignored if you set the reporter option.
retryBackoff: How long to wait before retrying a failed Datadog API call. Subsequent retries multiply this delay by 2^(retry count). For example, if this is set to 1, retries will happen after 1, then 2, then 4 seconds.
- Defaults to 1.
- Ignored if you set the reporter option.
reporter: An object that actually sends the buffered metrics. (optional)
- There are two built-in reporters you can use:
  1. reporters.DatadogReporter sends metrics to Datadog’s API, and is the default.
  2. reporters.NullReporter throws the metrics away. It’s useful for tests or temporarily disabling your metrics.

Example:

metrics.init({ host: 'myhost', prefix: 'myapp.' });

Disabling metrics using NullReporter:

metrics.init({ host: 'myhost', reporter: metrics.NullReporter() });

Send metrics to a totally different service instead of Datadog:

metrics.init({
  reporter: {
    async report(series) {
      // `series` is an array of metrics objects, formatted basically how the
      // Datadog v1 metrics API and v1 distributions API want them.
      const response = await fetch('https://my-datadog-like-api.com/series', {
        method: 'POST',
        body: JSON.stringify({ series })
      });
      return await response.json();
    }
  }
});

Gauges

metrics.gauge(key, value[, tags[, timestamp]])

Record the current value of a metric. The most recent value since the last flush 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:

metrics.gauge('test.mem_free', 23);

Counters

metrics.increment(key[, value[, tags[, timestamp]]])

Increment the counter by the given value (or 1 by default). Optionally, 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 Date.now().

Example:

metrics.increment('test.requests_served');
metrics.increment('test.awesomeness_factor', 10);

Histograms

metrics.histogram(key, value[, tags[, timestamp[, options]]])

Sample a histogram value. Histograms will produce metrics that describe the distribution of the recorded values, namely the minimum, maximum, average, median, 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:

metrics.histogram('test.service_time', 0.248);

You can also specify an options object to adjust which aggregations and percentiles should be calculated. For example, to only calculate an average, count, and 99th percentile:

metrics.histogram('test.service_time', 0.248, ['tag:value'], Date.now(), {
    // Aggregates can include 'max', 'min', 'sum', 'avg', 'median', or 'count'.
    aggregates: ['avg', 'count'],
    // Percentiles can include any decimal between 0 and 1.
    percentiles: [0.99]
});

Distributions

metrics.distribution(key, value[, tags[, timestamp]])

Send a distribution value. Distributions are similar to histograms (they create several metrics for count, average, percentiles, etc.), but they are calculated server-side on Datadog’s systems. This is much higher-overhead than histograms, and the individual calculations made from it have to be configured on the Datadog website instead of in the options for this package.

You should use this in environments where you have many instances of your application running in parallel, or instances constantly starting and stopping with different hostnames or identifiers and tagging each one separately is not feasible. AWS Lambda or serverless functions are a great example of this. In such environments, you also might want to use a distribution instead of increment or gauge (if you have two instances of your app sending those metrics at the same second, and they are not tagged differently or have different host names, one will overwrite the other — distributions will not).

Example:

metrics.distribution('test.service_time', 0.248);

Flushing

By default, datadog-metrics will automatically flush, or send accumulated metrics to Datadog, at regular intervals, and, in environments that support it, before your program exits. (However, if you call process.exit() to cause a hard exit, datadog-metrics doesn’t get a chance to flush. In this case, you may want to call await metrics.stop() first.)

You can adjust the interval by using the flushIntervalSeconds option. Setting it to 0 will disable auto-flushing entirely:

// Set auto-flush interval to 10 seconds.
metrics.init({ flushIntervalSeconds: 10 });

You can also send accumulated metrics manually at any time by calling metrics.flush().

Please note that, when calling the BufferedMetricsLogger constructor directly, flushIntervalSeconds defaults to 0 instead. When constructing your own logger this way, you must expicitly opt-in to auto-flushing by setting a positive value.

`metrics.flush()`

Sends any buffered metrics to Datadog and returns a promise. By default, flush() will be called for you automatically unless you set flushIntervalSeconds to 0 (see above for more details).

⚠️ This method used to take two callback arguments for handling successes and errors. That form is deprecated and will be removed in a future update:

// Deprecated:
metrics.flush(
    () => console.log('Flush suceeded!'),
    (error) => console.log('Flush error:', error)
);

// Current, using `await`:
try {
    await metrics.flush();
    console.log('Flush suceeded!');
} catch (error) {
    console.log('Flush error:', error);
}

// Or, using Promise callbacks:
metrics.flush()
    .then(() => console.log('Flush succeeded'))
    .catch((error) => console.log('Flush error:', error)) ;

`metrics.stop(options)`

Stops auto-flushing (if enabled) and flushes any currently buffered metrics. This is mainly useful if you want to manually clean up and send remaining metrics before hard-quitting your program (usually by calling process.exit()). Returns a promise for the result of the flush.

Takes an optional object with properties:

flush (boolean) Whether to flush any remaining metrics after stopping. Defaults to true.

Logging

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:

DEBUG=metrics node app.js

Contributing

Contributions are always welcome! For more info on how to contribute or develop locally, please see CONTRIBUTING.md.

Release History

In Development:

Breaking Changes:

TBD

New Features:

TBD

Deprecations:

TBD

Bug Fixes:

TBD

Maintenance:

TBD

Files

README.md

Latest commit

History

README.md

File metadata and controls

datadog-metrics

Installation

Example

Tutorial

Usage

Datadog API key

Module setup

Use case #1: Just let me track some metrics already!

Use case #2: I want some control over this thing!

Use case #3: Must. Control. Everything.

API

Initialization

Gauges

Counters

Histograms

Distributions

Flushing

metrics.flush()

metrics.stop(options)

Logging

Contributing

Release History

In Development:

0.12.1 (2024-12-18)

0.12.0 (2024-12-05)

0.11.4 (2024-11-10)

0.11.4-a.1 (2024-10-31)

0.11.3 (2024-10-31)

0.11.3a1 (2024-10-31)

0.11.2 (2024-06-25)

0.11.1 (2023-09-28)

0.11.0 (2022-02-21)

0.10.2 (2022-10-14)

0.10.1 (2022-09-11)

0.10.0 (2022-09-08)

0.9.3 (2021-03-22)

0.9.2 (2021-03-14)

0.9.1 (2021-02-19)

0.9.0 (2021-02-10)

0.8.2 (2020-11-16)

0.8.1

0.8.0

0.7.0

0.6.1

0.6.0

0.5.0

0.4.0

0.3.0

0.2.1

0.2.0

0.1.1

0.1.0

0.0.0

Meta

`metrics.flush()`

`metrics.stop(options)`