Metrics

We use this library internally to easily integrate AWS CloudWatch Custom Metrics into our applications.

To get started:

npm i @firstclasspostcodes/metrics -s

Now, add a configuration file named metrics.config.js to the working directory. This library uses cosmiconfig so name your file accordingly.

module.exports = {
  // Required: this is the namespace that all custom metrics will be published with
  namespace: 'Test/Service',
  // Required: the AWS region that the metrics will be published to
  region: process.env.AWS_REGION,
  // Optional: for serverless functions, specify `manualMode` to ensure that a metric
  // flush interval is not started.
  manualMode: true,
  // Required: define the custom metrics available to the application at runtime.
  metrics: {
    // this is the key that a custom metric will be configured as
    interestingMetric: {
      // Optional: a list of dimensions for the metric
      dimensions: [
        {
          Name: 'Function',
          Value: 'normalHandler',
        },
      ],
      // Optional: define the resolution for the metric, 1-60. Defaults to 60.
      resolution: 1,
      // Required: the type of metric being recorded
      unit: 'Count/Second',
    },
    longRunningFunction: {
      dimensions: [
        {
          Name: 'Function',
          Value: 'testHandler',
        },
      ],
      resolution: 1,
      // For measured functions, use milliseconds
      unit: 'Milliseconds',
    },
  },
};

For any deployed AWS applications, the correct IAM permissions must be configured:

Function:
  Type: 'AWS::Serverless::Function'
  Properties:
    # ...
    Policies:
      - CloudWatchPutMetricPolicy: {}

or defined explicitly:

Statement:
  - Effect: Allow
    Action:
      - cloudwatch:PutMetricData
    Resource:
      - '*'

Given the configuration above, you can use the configured metrics in the following way:

const metrics = require('@firstclasspostcodes/metrics');

const { longRunningFunc } = require('./example');

exports.handler = async (event) => {
  metrics.interestingMetric(event.someValue.length);

  // record the same metric with a custom dimension
  metrics.interestingMetric(event.someValue.length, [{
    countryName: 'United States',
  }])

  const data = await metrics.longRunningFunction(() => {
    // this will measure how long it takes to execute using perf_tools
    return longRunningFunc(event.someValue);
  }));

  // will log a warning to the console and ignore this
  metrics.doesNotExistMetric();

  // for lambda functions, make sure to flush metrics
  // before execution ends
  await metrics.flush();

  return data;
};