Class Metrics

Add a dimension to the metrics.

A dimension is a key-value pair that is used to group metrics.

See

https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension for more details.

Add multiple dimensions to the metrics.

A dimension is a key-value pair that is used to group metrics.

A high-cardinality data part of your Metrics log.

This is useful when you want to search highly contextual information along with your metrics in your logs.

Add a metric to the metrics buffer.

By default, metrics are buffered and flushed at the end of the Lambda invocation or when calling Metrics.publishStoredMetrics.

You can add a metric by specifying the metric name, unit, and value. For convenience, we provide a set of constants for the most common units in MetricUnit.

Example

import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
Copy

Optionally, you can specify the metric resolution, which can be either High or Standard. By default, metrics are published with a resolution of Standard, click here to learn more about metric resolutions.

Example

import { Metrics, MetricUnit, MetricResolution } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

metrics.addMetric('successfulBooking', MetricUnit.Count, 1, MetricResolution.High);
Copy

Create a singleMetric to capture cold start.

If it's a cold start invocation, this feature will:

• Create a separate EMF blob that contains a single metric named ColdStart
• Add function_name and service dimensions

This has the advantage of keeping cold start metric separate from your application metrics, where you might have unrelated dimensions, as well as avoiding potential data loss from metrics not being published for other reasons.

Example

import { Metrics } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

export const handler = async (_event: unknown, __context: unknown): Promise<void> => {
    metrics.captureColdStartMetric();
};
Copy

Clear all default dimensions.

Clear all dimensions.

Clear all metadata.

Clear all the metrics stored in the buffer.

A decorator automating coldstart capture, throw on empty metrics and publishing metrics on handler exit.

Example

import { Metrics } from '@aws-lambda-powertools/metrics';
import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

class Lambda implements LambdaInterface {
  @metrics.logMetrics({ captureColdStartMetric: true })
  public handler(_event: unknown, __context: unknown): Promise<void> {
    // ...
  }
}

const handlerClass = new Lambda();
export const handler = handlerClass.handler.bind(handlerClass);
Copy

Decorator

Class

Synchronous function to actually publish your metrics. (Not needed if using logMetrics decorator). It will create a new EMF blob and log it to standard output to be then ingested by Cloudwatch logs and processed automatically for metrics creation.

Example

import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' }); // Sets metric namespace, and service as a metric dimension

export const handler = async (_event: unknown, __context: unknown): Promise<void> => {
  metrics.addMetric('test-metric', MetricUnit.Count, 10);
  metrics.publishStoredMetrics();
};
Copy

Function to create a new metric object compliant with the EMF (Embedded Metric Format) schema which includes the metric name, unit, and optionally storage resolution.

The function will create a new EMF blob and log it to standard output to be then ingested by Cloudwatch logs and processed automatically for metrics creation.

See

https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html for more details

Sets default dimensions that will be added to all metrics.

Sets the function name to be added to the metric.

CloudWatch EMF uses the same dimensions across all your metrics. Use singleMetric if you have a metric that should have different dimensions.

You don't need to call publishStoredMetrics() after calling addMetric for a singleMetrics, they will be flushed directly.

Example

const singleMetric = metrics.singleMetric();
singleMetric.addDimension('InnerDimension', 'true');
singleMetric.addMetric('single-metric', MetricUnit.Percent, 50);
Copy

Throw an Error if the metrics buffer is empty.

Example

import { Metrics } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName:'orders' });

export const handler = async (_event: unknown, __context: unknown): Promise<void> => {
    metrics.throwOnEmptyMetrics();
    metrics.publishStoredMetrics(); // will throw since no metrics added.
};
Copy