Version 0.13.0-pre.1

This is a pre-release of v0.13.0 for testing. There are no new features, but this contains significant under-the-hood changes. We’ve slimmed things down by no longer relying on the official Datadog client, which is pretty heavy. If your app is pushing size or resource constraints, this update may help.

Breaking Changes:

• The minimum required Node.js version is now v14.0.0.

• The code property on AuthorizationError instances has been changed to DATADOG_METRICS_AUTHORIZATION_ERROR for clarity and consistency (it was previously DATADOG_AUTHORIZATION_ERROR). If you are using errorInstance.code to check types, make sure to update the string you were looking for.

Maintenance:

• Under the hood, we’ve removed a dependency on the official Datadog client (@datadog/datadog-api-client). This is an attempt to streamline the package, since the official client comes at a sizeable 15 MB of code for you to download and then load in your application. (#144)

Version 0.12.1

New Features:

• When auto-flushing is enabled, metrics are now also flushed before the process exits. In previous versions, you needed to do this manually by calling metrics.flush() at the every end of your program. (#141)

  You will still need to flush manually if you set flushIntervalSeconds to 0 or stop() (see below) if you are quitting your program by calling process.exit() (which interrupts a variety of operations).

• A new stop() method disables auto-flushing and flushes any currently buffered metrics (you can leave metrics in the buffer instead with the flush option: stop({flush: false})). (#141)

View diff

Version 0.12.0

Datadog-metrics now automatically retries failed metric submissions and uses promises for asynchronous actions! There are a handful of other deprecations and small improvements.

Breaking Changes:

• The DatadogReporter constructor now takes an options object instead of positional arguments. Using this constructor directly is pretty rare, so this should not affect most users. (#138)

New Features:

• Promises: asynchronous actions now use promises instead of callbacks. Callbacks are deprecated, but still work — they’ll be fully removed in v0.13.0. This affects:

  • The flush() method now returns a promise.
  • The report(series) method on any custom reporters should now return a promise. For now, datadog-metrics will use the old callback-based behavior if the method signature has callbacks listed after series argument.

  (See #125)

• Retries: flushes to Datadog’s API are now retried automatically. This can help you work around intermittent network issues or rate limits. To adjust retries, use the retries and retryBackoff options.

  metrics.init({
      // How many times to retry. To disable retries, set this to 0.
      retries: 2,
      // How long (in seconds) to wait between retries. Subsequent retries
      // wait exponentially longer.
      retryBackoff: 1
  });

  (See #138)

• Environment variables: you can now use either DATADOG_ or DD_ prefixes for environment variables (previously, only DATADOG_ worked). For example, you can set your API key via DATADOG_API_KEY or DD_API_KEY. (#137)

Deprecations:

• The appKey option is no longer supported. Application keys (as opposed to API keys) are not actually needed for sending metrics or distributions to the Datadog API. Including it in your configuration adds no benefits, but risks exposing a sensitive credential. (#127)

• The DATADOG_API_HOST environment variable is now deprecated. Please use DATADOG_SITE or DD_SITE instead (the apiHost option was renamed to site in v0.11.0, but the DATADOG_API_HOST environment variable was accidentally left as-is). (#134)

Version 0.11.4

This release updates the TypeScript types for this project, and doesn’t include any changes to functionality. There are also no changes since v0.11.4-a.1.

Bug Fixes:

• BufferedMetricsLogger is now an actual class & type when you import it in TypeScript. That is, you can now do:

  import { BufferedMetricsLogger } from 'datadog-metrics';
  
  function useLogger(logger: BufferedMetricsLogger) {
      // ...
  }

  Previously, you would have had to declare the type for logger as typeof BufferedMetricsLogger.prototype. (#120)

View diff

Version 0.11.4-a1

This pre-release is meant for testing a fix for #119.

Bug Fixes:

• Typings: Ensure BufferedMetricsLogger is seen as an actual class & type when importing in TypeScript. (#120)

Version 0.11.3

There are no changes since v0.11.2. This release exists to address a bad publish of a pre-release candidate.

Version 0.11.2

Fixes & Maintenance:

• Fix types and documentation for the aggregates option for histograms and the histogram.aggregates option for the library as a whole. It was previously listed as aggregations, which was incorrect. (Thanks to @Calyhre in #117.)

• Improve documentation and add a more detailed error message about API keys vs. application keys. (#118)

View diff

Version 0.11.1

Fixes & Maintenance:

• Resolve a deprecation warning from the underlying datadog-api-client library. This also updates the minimum required version of that library. (Thanks to @acatalucci-synth & @fcsonline in #112.)

View diff

v0.11.0

New Features:

• Built-in TypeScript definitions. If you use TypeScript, you no longer need to install separate type definitions from @types/datadog-metrics — they’re now built-in. Please make sure to remove @types/datadog-metrics from your dev dependencies.

  Even if you’re writing regular JavaScript, you should now see better autocomplete suggestions and documentation in editors that support TypeScript definitions (e.g. VisualStudio Code, WebStorm).

Breaking Changes:

• datadog-metrics now uses modern class syntax internally. In most cases, you shouldn’t need to change anything. However, if you are calling BufferedMetricsLogger.apply(...) or BufferedMetricsLogger.call(...), you’ll need to change your code to use new BufferedMetricsLogger(...) instead.

Deprecated Features:

• The apiHost option has been renamed to site so that it matches up with Datadog docs and official packages. The old apiHost name still works for now, but will be removed in the future.

• The reporters.DataDogReporter class has been renamed to reporters.DatadogReporter (lower-case D in "dog") so that it correctly matches Datadog’s actual name. The old name still works, but will be removed in the future.

View diff

v0.10.2

This release includes several new features and bugfixes!

New Features:

• Support for distribution metrics. You can now send distributions to Datadog by doing:

  const metrics = require('datadog-metrics');
  metrics.distribution('my.metric.name', 3.8, ['tags:here']);

  Distributions are similar to histograms (they create several metrics for count, average, percentiles, etc.), but they are calculated server-side on Datadog’s systems. For more details and guidance on when to use them, see:

  • The documentation in this project’s README
  • Datadog’s documentation at https://docs.datadoghq.com/metrics/distributions/

  (Thanks to @Mr0grog.)

• Add an onError option for handling asynchronous errors while flushing buffered metrics. You can use this to get details on an error or to send error info to a tracking service like Sentry.io:

  const metrics = require('datadog-metrics');
  metrics.init({
      onError (error) {
          console.error('There was an error sending to Datadog:', error);
      }
  });

• The built-in reporter classes are now available for you to use. If you need to disable the metrics library for some reason, you can now do so with:

  const metrics = require('datadog-metrics');
  metrics.init({
      reporter: new metrics.reporters.NullReporter(),
  });

  (Thanks to @Mr0grog.)

• Add an option for setting histogram defaults. In v0.10.0, the histogram() function gained the ability to set what aggregations and percentiles it generates with a final options argument. You can now specify a histogram option for init() or BufferedMetricsLogger in order to set default options for all calls to histogram(). Any options you set in the actual histogram() call will layer on top of the defaults:

  const metrics = require('datadog-metrics');
  metrics.init({
      histogram: {
          aggregations: ['sum', 'avg'],
          percentiles: [0.99]
      }
  });
  
  // Acts as if the options had been set to:
  // { aggregations: ['sum', 'avg'], percentiles: [0.99] }
  metrics.histogram('my.metric.name', 3.8);
  
  // Acts as if the options had been set to:
  // { aggregations: ['sum', 'avg'], percentiles: [0.5, 0.95] }
  metrics.histogram('my.metric.name', 3.8, [], Date.now(), {
      percentiles: [0.5, 0.95]
  });

  (Thanks to @Mr0grog.)

• Add a .median aggregation for histograms. When you log a histogram metric, it ultimately creates several metrics that track the minimum value, average value, maximum value, etc. There is now one that tracks the median value. StatsD creates the same metric from histograms, so you may find this useful if transitioning from StatsD. (Thanks to @Mr0grog.)

• This package no longer locks specific versions of its dependencies (instead, your package manager can choose any version that is compatible). This may help when deduplicating packages for faster installs or smaller bundles. (Thanks to @Mr0grog.)

Bug Fixes:

• Don’t use unref() on timers in non-Node.js environments. This is a step towards browser compatibility, although we are not testing browser-based usage yet. (Thanks to @Mr0grog.)
• The apiHost option was broken in v0.10.0 and now works again. (Thanks to @Mr0grog and @npeters.)
• Creating a second instance of BufferedMetricsLogger will no longer change the credentials used by previously created BufferedMetricsLogger instances. (Thanks to @Mr0grog.)

Internal Updates:

• Renamed the default branch in this repo to main. (Thanks to @dbader.)
• Use GitHub actions for continuous integration. (Thanks to @Mr0grog.)
• Code style cleanup. (Thanks to @Mr0grog.)
• When flushing, send each metric with its own list of tags. This helps mitigate subtle errors where a change to one metric’s tags may affect others. (Thanks to @Mr0grog.)

View diff