@financial-times/community-js-metrics v3.0.2

community-js-metrics

Metrics for community javascript and typescript projects

General Description

This module exports a singleton, an instance of MetricsClient, with extends EventEmitter with the following Events and Methods.

Usage

This library can send metrics to either graphite, cloudwatch or both. If running on AWS Lambda, then sending metrics to cloudwatch is the default, otherwise graphite will be used.

If needing to send metrics to graphite see the guide section for instructions on how to get the required environment variables.

To start sending metrics, you can just call the count() or histogram() methods as required.

For custom configuration for either cloudwatch or graphite; the init() method can be used.

Events

error

If an underlying MetricsDestinationStream errors, the error is propagated to the client.

import { metrics } from '@financial-times/community-js-metrics'

metrics.on('error', (error) => {
    console.error(error)
})

Properties

metrics.autoInit

A boolean value which determines whether metrics will be auto initialised when metrics.count() or metrics.histogram() is first called. Defaults to true.

Example:

import { metrics } from '@financial-times/community-js-metrics'

metrics.autoInit = false

Methods

metrics.init(options?:InitOptions)

Initialises metrics and configures destination streams. This is called automatically when metrics.count() or metrics.histogram() is first called unless metrics.autoInit is set to false.

Arguments:

• options (optional): MetricsClientInitOptions
• options.graphite (optional): Boolean | GraphiteDestinationStreamOptions - defaults to true when not running on AWS Lambda
• options.cloudwatch (optional): Boolean | CloudWatchDestinationStreamOptions - defaults to true when running on AWS Lambda

Returns: Promise<void>

Example:

import { metrics } from '@financial-times/community-js-metrics'

const metricsInitOptions = {
    graphite: true,
    cloudwatch: true
}
metrics.init(metricsInitOptions)

metrics.count(metricName:string, increment: number = 1)

Records one or more occurrences of an event in metrics and sends to the destinationStreams.

Arguments:

• metricName: string - the dot separated name for your metric i.e. 'didThing.success' or 'didThing.failure'
• increment: number - the number of times the thing happened, defaults to 1

Returns: void

Example:

import { metrics } from '@financial-times/community-js-metrics'

metrics.count('didThing.success', 22)

metrics.histogram(metricName:string, value: number)

Records a numeric quantity associated with and event in metrics and sends to the destinationStreams

Arguments:

• metricName: string - the dot separated name for your metric i.e. 'didThing.success' or 'didThing.failure'
• value: number - the size of the thing that happened, i.e. duration

Returns: void

Example:

import { metrics } from '@financial-times/community-js-metrics'

metrics.histogram('didThing.response.time', 180)

metrics.end()

Ends all destination streams.

Returns: Promise<void>

Example:

await metric.end()

MetricsDestinationStreams

This library allows the sending of metrics to multiple destinations if required. These are configured at initialisation and the available destinations are listed below.

GraphiteDestinationStream

Constructor Arguments

• options (optional): GraphiteDestinationStreamOptions
• options.metricsPrefix (optional): String - the prefix to use for your metrics, i.e. '<uuid>.foo.bar.baz', see note below for defaults.
• options.host (optional): String - the graphite host to send your metrics to, defaults to 'graphitev2.ft.com'
• options.port (optional): Number - the port on the graphite host to send the metrics to, defaults to 2003

Note If options.metricPrefix is not set, the metricsPrefix is built up from the following environment variables:

1) FT_GRAPHITE_APP_UUID - will throw an error on instantiation if this is not set 2) ENVIRONMENT or NODE_ENV - will default to 'unknown' if not set 3) DYNO or AWS_LAMBDA_FUNCTION_NAME* or INSTANCE_ID - will default to 'unknown' if not set

* if SYSTEM_CODE is set and either ENVIRONMENT or NODE_ENV, the <system-code>-<env>- prefix will be stripped from this value.

Example

import {GraphiteDestinationStream} from '@financial-times/community-js-metrics/GraphiteDestinationStream'

const opts = {/* ...opts */}
const graphiteDestinationStream = new GraphiteDestinationStream(opts)

CloudWatchDestinationStream

Constructor Arguments

• options (optional): CloudWatchDestinationStreamOptions
• options.clientConfig ( optional): CloudWatchClientConfig - the config you wish to use to initialise the CloudWatchClient
• options.namespace (optional): String - the namespace in which you want your metrics placed (see note below for details of defaults)
• options.dimensions (optional): Dimension[] - the dimensions you wish your metrics to have, (see note below for details of defaults)

Note If options.namespace is not set, the namespace will be FT/<system-code> where <system-code> is obtained from the SYSTEM_CODE environment variable. An error will be thrown if this environment variable is not set.

If options.dimensions is not set, default dimensions will be added from the below environment variables, if they are set:

• ENVIRONMENT
• NODE_ENV
• DYNO
• AWS_LAMBDA_FUNCTION_NAME ( if SYSTEM_CODE is set and either ENVIRONMENT or NODE_ENV, the <system-code>-<env>- prefix will be stripped from this value)
• INSTANCE_ID

Example

import {CloudWatchDestinationStream} from '@financial-times/community-js-metrics/CloudWatchDestinationStream'

const opts = {/* ...opts */}
const cloudWatchDestinationStream = new CloudWatchDestinationStream(opts)

Examples

Lambda/Serverless

In a lambda function, simply init at the start and end at the end of each invocation.

const metrics = require('@financial-times/community-js-metrics')

export async function handler(event, context) {
    try {
        await metrics.init()
        metrics.on('error', (error) => {
            console.error('metrics_error', error)
        })
        // handler code...
    } catch (error) {
        // log errors
    } finally {
        await metrics.end()
    }
}

Guides etc

Getting an FT_GRAPHITE_APP_UUID for Graphite metrics

First add a FT_GRAPHITE_APP_UUID to your projects shared env vars. This uuid can be obtained via the /graphiteuuid slackbot, i.e with:

/graphiteuuid community.<system-code> <system-code> community.engineering@ft.com

Replace <host-platform> with the relevant host platform, e.g. lambda, ecs or heroku. Replace <system-code> with the system code of your service (this needs to already exist in BizOps).

Then add it to the shared secrets in vault, i.e. in: secret/teams/community/<system-code>/shared