# Metric

A metric emitted by a service.

The metric is a combination of a metric identifier (namespace, name and dimensions)
and an aggregation function (statistic, period and unit).

It also contains metadata which is used only in graphs, such as color and label.
It makes sense to embed this in here, so that compound constructs can attach
that metadata to metrics they expose.

This class does not represent a resource, so hence is not a construct. Instead,
Metric is an abstraction that makes it easy to specify metrics for use in both
alarms and graphs.

Extends: Metric
Implements: IMetric

- Source: [`aws-cloudwatch/lib/metric.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-cloudwatch/lib/metric.ts#L404)
- Type last changed: v2.204.0 · 4 Jul 2025

## Example

```ts
declare const serverlessCache: elasticache.ServerlessCache;

// The 5 minutes average of the total number of successful read-only key lookups in the cache.
const cacheHits = serverlessCache.metricCacheHitCount();

// The 5 minutes average of the total number of bytes used by the data stored in the cache.
const bytesUsedForCache = serverlessCache.metricDataStored();

// The 5 minutes average of the total number of ElastiCacheProcessingUnits (ECPUs) consumed by the requests executed on the cache.
const elastiCacheProcessingUnits = serverlessCache.metricProcessingUnitsConsumed();

// Create an alarm for ECPUs.
elastiCacheProcessingUnits.createAlarm(this, 'ElastiCacheProcessingUnitsAlarm', {
  threshold: 50,
  evaluationPeriods: 1,
});
```

## Initializer

```ts
new Metric(props: MetricProps)
```

## Properties

- `account`: string — Account which this metric comes from.

- `color`: string — The hex color code used when this metric is rendered on a graph.

- `dimensions`: { [key: string]: any } — Dimensions of this metric.

- `id`: string — Unique identifier for this metric when used in dashboard widgets.

- `label`: string — Label for this metric when added to a Graph in a Dashboard.

- `metricName`: string — Name of this metric.

- `namespace`: string — Namespace of this metric.

- `period`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — Period of this metric.

- `region`: string — Region which this metric comes from.

- `statistic`: string — Statistic of this metric.

- `unit`: [Unit](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudwatch.Unit.html) — Unit of the metric.

- `visible`: boolean — Whether this metric should be visible in dashboard graphs.

- `warnings`: string[] — - use warningsV2

- `warningsV2`: { [key: string]: string } — Warnings attached to this metric.

## Methods

- `anomalyDetectionFor(props: AnomalyDetectionMetricOptions): MathExpression` (static) — Creates an anomaly detection metric from the provided metric.

  **Parameters**

  - `props` — The anomaly detection alarm properties.

  **Returns:** An anomaly detection metric

- `attachTo(scope: IConstruct): Metric // chainable` — Attach the metric object to the given construct scope.

  Returns a Metric object that uses the account and region from the Stack
  the given construct is defined in. If the metric is subsequently used
  in a Dashboard or Alarm in a different Stack defined in a different
  account or region, the appropriate 'region' and 'account' fields
  will be added to it.

  If the scope we attach to is in an environment-agnostic stack,
  nothing is done and the same Metric object is returned.

- `createAlarm(scope: Construct, id: string, props: CreateAlarmOptions): Alarm` — Make a new Alarm for this metric.

  Combines both properties that may adjust the metric (aggregation) as well
  as alarm properties.

- `grantPutMetricData(grantee: IGrantable): Grant` (static) — Grant permissions to the given identity to write metrics.

  **Parameters**

  - `grantee` — The IAM identity to give permissions to.

- `toMetricConfig(): MetricConfig` — Inspect the details of the metric object.

- `toString(): string` — Returns a string representation of an object.

- `with(props: MetricOptions): Metric // chainable` — Return a copy of Metric `with` properties changed.

  All properties except namespace and metricName can be changed.

  **Parameters**

  - `props` — The set of properties to change.