Add multiple dimensions to the metrics.
This method is useful when you want to add multiple dimensions to the metrics at once.
When calling the publishStoredMetrics() method, the dimensions are cleared. This type of
dimension is useful when you want to add request-specific dimensions to your metrics. If you want to add dimensions that are
included in all metrics, use the setDefaultDimensions() method.
An object with key-value pairs of dimensions
A metadata key-value pair to be included with metrics.
You can use this method to add high-cardinality data as part of your metrics. This is useful when you want to search highly contextual information along with your metrics in your logs.
Note that the metadata is not included in the Amazon CloudWatch UI, but it can be used to search and filter logs.
The key of the metadata
The value of the metadata
import { Metrics } from '@aws-lambda-powertools/metrics';
const metrics = new Metrics({
namespace: 'serverlessAirline',
serviceName: 'orders'
});
export const handler = async (event) => {
metrics.addMetadata('request_id', event.requestId);
metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
metrics.publishStoredMetrics();
};
Add a metric to the metrics buffer.
By default, metrics are buffered and flushed when calling publishStoredMetrics() method,
or at the end of the handler function when using the logMetrics() decorator or the Middy.js middleware.
Metrics are emitted to standard output in the Amazon CloudWatch EMF (Embedded Metric Format) schema. In AWS Lambda, the logs are automatically picked up by CloudWatch logs and processed asynchronously.
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 the MetricUnit dictionary object.
Optionally, you can specify a resolution, which can be either High or Standard, using the MetricResolution dictionary object.
By default, metrics are published with a resolution of Standard.
The metric name
The metric unit, see MetricUnit
The metric value
Optionalresolution: MetricResolutionThe metric resolution, see MetricResolution
Immediately emit a ColdStart metric if this is a cold start invocation.
A cold start is when AWS Lambda initializes a new instance of your function. To take advantage of this feature, you must instantiate the Metrics class outside of the handler function.
By using this method, the metric will be emitted immediately without you having to call publishStoredMetrics().
If you are using the logMetrics() decorator, or the Middy.js middleware, you can enable this
feature by setting the captureColdStartMetric option to true.
Clear all previously set default dimensions.
This will remove all default dimensions set by the setDefaultDimensions() method
or via the defaultDimensions parameter in the constructor.
import { Metrics } from '@aws-lambda-powertools/metrics';
const metrics = new Metrics({
namespace: 'serverlessAirline',
serviceName: 'orders',
defaultDimensions: { environment: 'dev' },
});
metrics.setDefaultDimensions({ region: 'us-west-2' });
// both environment and region dimensions are removed
metrics.clearDefaultDimensions();
Clear all the dimensions added to the Metrics instance via addDimension() or addDimensions().
These dimensions are normally cleared when calling publishStoredMetrics(), but
you can use this method to clear specific dimensions that you no longer need at runtime.
This method does not clear the default dimensions set via setDefaultDimensions() or via
the defaultDimensions parameter in the constructor.
import { Metrics } from '@aws-lambda-powertools/metrics';
const metrics = new Metrics({
namespace: 'serverlessAirline',
serviceName: 'orders'
});
export const handler = async () => {
metrics.addDimension('region', 'us-west-2');
// ...
metrics.clearDimensions(); // olnly the region dimension is removed
};
The method is primarily intended for internal use, but it is exposed for advanced use cases.
Clear all the metadata added to the Metrics instance.
Metadata is normally cleared when calling publishStoredMetrics(), but
you can use this method to clear specific metadata that you no longer need at runtime.
The method is primarily intended for internal use, but it is exposed for advanced use cases.
A class method decorator to automatically log metrics after the method returns or throws an error.
The decorator can be used with TypeScript classes and can be configured to optionally capture a ColdStart metric (see captureColdStartMetric()),
throw an error if no metrics are emitted (see setThrowOnEmptyMetrics()),
and set default dimensions for all metrics (see setDefaultDimensions()).
Optionaloptions: ExtraOptionsOptions to configure the behavior of the decorator, see ExtraOptions
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) {
// ...
}
}
const handlerClass = new Lambda();
export const handler = handlerClass.handler.bind(handlerClass);
You can configure the decorator with the following options:
captureColdStartMetric: Whether to capture a ColdStart metricdefaultDimensions: Default dimensions to add to all metricsthrowOnEmptyMetrics: Whether to throw an error if no metrics are emittedFlush the stored metrics to standard output.
The method empties the metrics buffer and emits the metrics to standard output in the Amazon CloudWatch EMF (Embedded Metric Format) schema.
When using the logMetrics() decorator, or the Middy.js middleware, the metrics are automatically flushed after the handler function returns or throws an error.
Serialize the stored metrics into a JSON object compliant with the Amazon CloudWatch EMF (Embedded Metric Format) schema.
The EMF schema is a JSON object that contains the following properties:
_aws: An object containing the timestamp and the CloudWatch metrics.CloudWatchMetrics: An array of CloudWatch metrics objects.Namespace: The namespace of the metrics.Dimensions: An array of dimensions for the metrics.Metrics: An array of metric definitions.The serialized object is returned for later use.
This is primarily an internal method used by the Metrics class, but it is exposed for advanced use cases.
Set default dimensions that will be added to all metrics.
This method will merge the provided dimensions with the existing default dimensions.
The dimensions to be added to the default dimensions object
import { Metrics } from '@aws-lambda-powertools/metrics';
const metrics = new Metrics({
namespace: 'serverlessAirline',
serviceName: 'orders',
defaultDimensions: { environment: 'dev' },
});
// Default dimensions will contain both region and environment
metrics.setDefaultDimensions({
region: 'us-west-2',
environment: 'prod',
});
Set the function name to be added to each metric as a dimension.
When using the logMetrics() decorator, or the Middy.js middleware, the function
name is automatically inferred from the Lambda context.
The function name
Set the flag to throw an error if no metrics are emitted.
You can use this method to enable or disable this opt-in feature. This is useful if you want to ensure that at least one metric is emitted when flushing the metrics. This can be useful to catch bugs where metrics are not being emitted as expected.
Whether to throw an error if no metrics are emitted
Sets the timestamp for the metric.
If an integer is provided, it is assumed to be the epoch time in milliseconds. If a Date object is provided, it will be converted to epoch time in milliseconds.
The timestamp must be a Date object or an integer representing an epoch time. This should not exceed 14 days in the past or be more than 2 hours in the future. Any metrics failing to meet this criteria will be skipped by Amazon CloudWatch.
See: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html See: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html
The timestamp to set, which can be a number or a Date object.
import { MetricUnit, Metrics } from '@aws-lambda-powertools/metrics';
const metrics = new Metrics({
namespace: 'serverlessAirline',
serviceName: 'orders',
});
export const handler = async () => {
const metricTimestamp = new Date(Date.now() - 24 * 60 * 60 * 1000); // 24 hours ago
metrics.setTimestamp(metricTimestamp);
metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
};
Create a new Metrics instance configured to immediately flush a single metric.
CloudWatch EMF uses the same dimensions and timestamp across all your metrics, this is useful when you have a metric that should have different dimensions or when you want to emit a single metric without buffering it.
This method is used internally by the captureColdStartMetric() method to emit the ColdStart metric immediately
after the handler function is called.
import { Metrics } from '@aws-lambda-powertools/metrics';
const metrics = new Metrics({
namespace: 'serverlessAirline',
serviceName: 'orders'
});
export const handler = async () => {
const singleMetric = metrics.singleMetric();
// The single metric will be emitted immediately
singleMetric.addMetric('coldStart', MetricUnit.Count, 1);
// These other metrics will be buffered and emitted when calling `publishStoredMetrics()`
metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
metrics.publishStoredMetrics();
Add a dimension to metrics.
A dimension is a key-value pair that is used to group metrics, and it is included in all metrics emitted after it is added.
When calling the
publishStoredMetrics()method, the dimensions are cleared. This type of dimension is useful when you want to add request-specific dimensions to your metrics. If you want to add dimensions that are included in all metrics, use thesetDefaultDimensions()method.