Datadog Metrics Reporter

Common errors

• Error: Datadog API key is not configured. Set the 'DD_API_KEY' environment variable or pass an 'apiKey' option.

  cause The Datadog API key was not provided during initialization.
  fix Set the `DD_API_KEY` environment variable or explicitly pass an `apiKey` string in the options object to `metrics.init()` or `new BufferedMetricsLogger()`.

• TypeError: metrics.gauge is not a function (or increment/histogram/distribution)

  cause Attempted to use metric reporting functions (e.g., `metrics.gauge()`) before `metrics.init()` has been called.
  fix Ensure `metrics.init()` is called and completes successfully before any other metric reporting functions are invoked on the global `metrics` object.

• Error: The 'metrics' object has already been initialized.

  cause The `metrics.init()` function was called multiple times, which is not allowed for the global metrics object.
  fix Ensure `metrics.init()` is called only once in your application's lifecycle. If you need multiple independent loggers, use `new BufferedMetricsLogger()` instead.

Warnings

• breaking The minimum required Node.js version has been bumped from v12.0.0 to v14.0.0.
  Fix: Ensure your Node.js environment is at least v14.0.0 before upgrading to v0.13.0 or later.
• breaking The `code` property on `AuthorizationError` instances has been changed to `DATADOG_METRICS_AUTHORIZATION_ERR`.
  Fix: Update any error handling logic that inspects the `code` property of `AuthorizationError` instances to use the new string literal.
• gotcha Since v0.12.1, metrics are automatically flushed before the process exits. However, if `flushIntervalSeconds` is set to `0` or `process.exit()` is called, manual flushing via `metrics.flush()` is still required to guarantee all metrics are sent.
  Fix: For critical metrics or specific exit scenarios, explicitly call `metrics.flush()` and await its completion before `process.exit()` or when `flushIntervalSeconds` is zero.
• breaking Asynchronous actions, such as `flush()`, now exclusively use Promises instead of callbacks. Callback arguments are no longer supported.
  Fix: Refactor any asynchronous operations to use Promise-based syntax (e.g., `async/await` or `.then/.catch`) instead of passing callback functions.
• breaking The `DatadogReporter` constructor now requires an options object instead of positional arguments. This primarily affects users directly instantiating the reporter.
  Fix: If you are directly using `new DatadogReporter(...)`, update your constructor call to pass a single options object.
• deprecated Built-in TypeScript definitions were introduced in v0.11.0. The separate `@types/datadog-metrics` package is no longer needed and should be removed from your `devDependencies`.
  Fix: Remove `@types/datadog-metrics` from your `package.json` and `npm install` or `yarn install`.
• gotcha The option for configuring histogram aggregates was previously misdocumented and typed as `aggregations`. It has been corrected to `aggregates`.
  Fix: Ensure you are using the `aggregates` option when configuring histogram behavior, not `aggregations`.

Install

• npm install datadog-metrics npm
• yarn add datadog-metrics yarn
• pnpm add datadog-metrics pnpm

Imports

• init
  wrong:

  const init = require('datadog-metrics').init;

  correct:

  import { init } from 'datadog-metrics';

  Initializes the global metrics object. For CommonJS, you'd typically `const metrics = require('datadog-metrics'); metrics.init(...)` then use `metrics.gauge` etc.
• BufferedMetricsLogger
  wrong:

  import BufferedMetricsLogger from 'datadog-metrics';

  correct:

  import { BufferedMetricsLogger } from 'datadog-metrics';

  This is a named export for creating independent metric loggers. Correctly typed as a class since v0.11.4.
• metrics global object
  wrong:

  import metrics from 'datadog-metrics';

  correct:

  import * as metrics from 'datadog-metrics';

  After calling `metrics.init()`, functions like `metrics.gauge()` and `metrics.increment()` are available directly on the imported `metrics` object.

Quickstart

Demonstrates initializing the global metrics reporter and sending various metric types (gauge, increment, histogram, distribution). Also shows how to create and use a separate BufferedMetricsLogger instance for isolated metric collection, and how to perform an explicit flush operation.

import { init, BufferedMetricsLogger } from 'datadog-metrics';

// Initialize the global metrics object
init({
  apiKey: process.env.DD_API_KEY ?? '',
  appKey: process.env.DD_APP_KEY ?? '', // Optional, for advanced features/error details
  host: 'my-app-server',
  prefix: 'my_app.',
  tags: ['env:production', 'region:us-east-1'],
  flushIntervalSeconds: 15,
  // Optional: configure to use custom logger for more control
  // logger: console,
});

// Send some metrics using the global instance
metrics.gauge('user_sessions', 1234, ['browser:chrome']);
metrics.increment('request_count', 1, ['status:200']);
metrics.histogram('api_response_time', 150.5, ['endpoint:/data']);
metrics.distribution('task_duration_ms', 55.2, ['task_name:process_batch']);

console.log('Metrics sent via global instance.');

// Create and use a separate buffered logger instance
const customLogger = new BufferedMetricsLogger({
  apiKey: process.env.DD_API_KEY ?? '',
  host: 'custom-worker',
  prefix: 'worker_process.',
  tags: ['worker_id:42', 'queue:high_prio'],
});

customLogger.gauge('queue_depth', 5);
customLogger.increment('job_processed');
console.log('Metrics sent via custom logger instance.');

// Manual flush (optional, auto-flush on exit since v0.12.1)
// In a real application, you might want to wait for these promises
Promise.all([
  metrics.flush(),
  customLogger.flush()
]).then(() => {
  console.log('All metrics manually flushed.');
}).catch(err => {
  console.error('Error flushing metrics:', err);
});