seek-datadog-custom-metrics

🐶 Datadog Custom Metrics

Common interface for sending Datadog custom metrics from Node.js runtime environments:

• Containers (via hot-shots)
• AWS Lambda (via Datadog's CloudWatch integration)

yarn add seek-datadog-custom-metrics

Table of contents

• Tagging convention
• API reference
  • createStatsDClient
  • createCloudWatchClient
  • createNoOpClient
  • createTimedSpan
• Contributing

Tagging convention

All custom metrics are prefixed by AppConfig.name. Two global tags are also added to every custom metric:

• AppConfig.environment becomes env:${value}
• AppConfig.version becomes version:${value}

These tags are consistent with tags sent by Gantry via Datadog's AWS integration.

API reference

createStatsDClient

createStatsDClient creates a hot-shots client configured with our tagging convention. This is intended for containerized services, particularly those deployed with Gantry.

import { createStatsDClient } from 'seek-datadog-custom-metrics';

// Expects `name`, `version`, `environment` and `metricsServer` properties
import config from '../config';

// This example assumes Bunyan/pino
import { rootLogger } from '../logger';
const errorHandler = (err: Error) => {
  rootLogger.error('StatsD error', err);
};

// Returns a standard hot-shots StatsD instance
const metricsClient = createStatsDClient(config, errorHandler);

createCloudWatchClient

createCloudWatchClient returns a client that uses Datadog's CloudWatch integration. This is intended for use in Lambda functions.

import { createCloudWatchClient } from 'seek-datadog-custom-metrics';

// Expects `name`, `version` and `environment` properties
import config from '../config';

// Returns a `MetricsClient` subset of the full StatsD interface
const metricsClient = createCloudWatchClient(config);

createNoOpClient

createNoOpClient returns a no-op client. This is intended for use where a MetricsClient interface is expected but you do not wish to provide one, e.g in tests.

import { createNoOpClient } from 'seek-datadog-custom-metrics';

// Returns a `MetricsClient` subset of the full StatsD interface
const metricsClient = createNoOpClient();

createTimedSpan

createTimedSpan wraps an asynchronous closure and records custom Datadog metrics about its performance. This is intended as a lightweight alternative to APM where nested spans aren't required.

import { createTimedSpan } from 'seek-datadog-custom-metrics';

// Takes a StatsD instance or `MetricsClient`
const timedSpan = createTimedSpan(metricsClient);

const loadPrivateKey = async (): Promise<PrivateKey> =>
  await timedSpan(
    // Prefix for the custom metrics
    'secrets.load_private_key',
    // Closure to be timed
    () => client.getSecretValue({ SecretId }).promise(),
  );