@aws-cdk/metrics-facade-alpha

Metrics Facade Alpha Library

Version 2.274.0-alpha.0

Separate package

@aws-cdk/metrics-facade-alpha is not part of aws-cdk-lib — install it separately:

npm install @aws-cdk/metrics-facade-alpha
pip install aws-cdk.metrics-facade-alpha

This module is experimental (alpha): its API may change in any release, without a major version bump.

---

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

---

CloudWatch Metrics

This library automatically generates typed CloudWatch metric helpers for AWS resources. These metrics come in two flavors: resource-scoped and unscoped.

Resource-Scoped Metrics

Resource-scoped metrics are created from a resource reference (e.g. a Lambda function). The resource dimensions are automatically injected, so metric methods return metrics already filtered to that specific resource.

Metrics Basic Usage

import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
import { LambdaMetrics } from '@aws-cdk/metrics-facade-alpha/aws-lambda';

// Works with L2 constructs
declare const fn: lambda.Function;
const fnMetrics = LambdaMetrics.fromFunction(fn);

new cloudwatch.Alarm(scope, 'ErrorAlarm', {
  metric: fnMetrics.errors(),
  threshold: 5,
  evaluationPeriods: 1,
  comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
});

// Also works with L1 constructs
declare const cfnFunction: lambda.CfnFunction;
const cfnMetrics = LambdaMetrics.fromFunction(cfnFunction);

import aws_cdk.aws_lambda as lambda_
import aws_cdk.aws_cloudwatch as cloudwatch
from aws_cdk.metrics_facade_alpha.aws_lambda import LambdaMetrics

# Works with L2 constructs
# fn: lambda.Function

# Also works with L1 constructs
# cfn_function: lambda.CfnFunction

fn_metrics = LambdaMetrics.from_function(fn)

cloudwatch.Alarm(scope, "ErrorAlarm",
    metric=fn_metrics.errors(),
    threshold=5,
    evaluation_periods=1,
    comparison_operator=cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD
)
cfn_metrics = LambdaMetrics.from_function(cfn_function)

import software.amazon.awscdk.services.lambda.*;
import software.amazon.awscdk.services.cloudwatch.*;
import aws.cdk.metrics.facade.alpha.aws.lambda.LambdaMetrics;

// Works with L2 constructs
Function fn;

// Also works with L1 constructs
CfnFunction cfnFunction;

FunctionMetrics fnMetrics = LambdaMetrics.fromFunction(fn);

Alarm.Builder.create(scope, "ErrorAlarm")
        .metric(fnMetrics.errors())
        .threshold(5)
        .evaluationPeriods(1)
        .comparisonOperator(ComparisonOperator.GREATER_THAN_THRESHOLD)
        .build();
FunctionMetrics cfnMetrics = LambdaMetrics.fromFunction(cfnFunction);

using Amazon.CDK.AWS.Lambda;
using Amazon.CDK.AWS.CloudWatch;
using Aws.Cdk.Metrics.Facade.Alpha.Aws.Lambda;

// Works with L2 constructs
Function fn;

// Also works with L1 constructs
CfnFunction cfnFunction;

var fnMetrics = LambdaMetrics.FromFunction(fn);

new Alarm(scope, "ErrorAlarm", new AlarmProps {
    Metric = fnMetrics.Errors(),
    Threshold = 5,
    EvaluationPeriods = 1,
    ComparisonOperator = ComparisonOperator.GREATER_THAN_THRESHOLD
});
var cfnMetrics = LambdaMetrics.FromFunction(cfnFunction);

import lambda "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws-samples/dummy/awscdkmetricsfacadealpha/awslambda"

// Works with L2 constructs
var fn Function

// Also works with L1 constructs
var cfnFunction CfnFunction

fnMetrics := awscdkmetricsfacadealphaawslambda.LambdaMetrics_FromFunction(fn)

cloudwatch.NewAlarm(scope, jsii.String("ErrorAlarm"), &AlarmProps{
	Metric: fnMetrics.errors(),
	Threshold: jsii.Number(5),
	EvaluationPeriods: jsii.Number(1),
	ComparisonOperator: cloudwatch.ComparisonOperator_GREATER_THAN_THRESHOLD,
})
cfnMetrics := awscdkmetricsfacadealphaawslambda.LambdaMetrics_FromFunction(cfnFunction)

Metric Features

import * as lambda from 'aws-cdk-lib/aws-lambda';
import { LambdaMetrics } from '@aws-cdk/metrics-facade-alpha/aws-lambda';

declare const fn: lambda.Function;
const fnMetrics = LambdaMetrics.fromFunction(fn);

// FunctionName dimension is automatically injected from the function reference
const metric = fnMetrics.invocations();

import aws_cdk.aws_lambda as lambda_
from aws_cdk.metrics_facade_alpha.aws_lambda import LambdaMetrics

# fn: lambda.Function

fn_metrics = LambdaMetrics.from_function(fn)

# FunctionName dimension is automatically injected from the function reference
metric = fn_metrics.invocations()

import software.amazon.awscdk.services.lambda.*;
import aws.cdk.metrics.facade.alpha.aws.lambda.LambdaMetrics;

Function fn;

FunctionMetrics fnMetrics = LambdaMetrics.fromFunction(fn);

// FunctionName dimension is automatically injected from the function reference
IMetric metric = fnMetrics.invocations();

using Amazon.CDK.AWS.Lambda;
using Aws.Cdk.Metrics.Facade.Alpha.Aws.Lambda;

Function fn;

var fnMetrics = LambdaMetrics.FromFunction(fn);

// FunctionName dimension is automatically injected from the function reference
var metric = fnMetrics.Invocations();

import lambda "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws-samples/dummy/awscdkmetricsfacadealpha/awslambda"

var fn Function

fnMetrics := awscdkmetricsfacadealphaawslambda.LambdaMetrics_FromFunction(fn)

// FunctionName dimension is automatically injected from the function reference
metric := fnMetrics.invocations()

Statistic Override: Override default statistics via MetricOptions

import * as lambda from 'aws-cdk-lib/aws-lambda';
import { LambdaMetrics } from '@aws-cdk/metrics-facade-alpha/aws-lambda';

declare const fn: lambda.Function;
const fnMetrics = LambdaMetrics.fromFunction(fn);

// Default statistic for Duration is Average
const defaultMetric = fnMetrics.duration();

// Override statistic via MetricOptions
const p99Metric = fnMetrics.duration({ statistic: 'p99' });

import aws_cdk.aws_lambda as lambda_
from aws_cdk.metrics_facade_alpha.aws_lambda import LambdaMetrics

# fn: lambda.Function

fn_metrics = LambdaMetrics.from_function(fn)

# Default statistic for Duration is Average
default_metric = fn_metrics.duration()

# Override statistic via MetricOptions
p99_metric = fn_metrics.duration(statistic="p99")

import software.amazon.awscdk.services.lambda.*;
import aws.cdk.metrics.facade.alpha.aws.lambda.LambdaMetrics;

Function fn;

FunctionMetrics fnMetrics = LambdaMetrics.fromFunction(fn);

// Default statistic for Duration is Average
IMetric defaultMetric = fnMetrics.duration();

// Override statistic via MetricOptions
IMetric p99Metric = fnMetrics.duration(MetricOptions.builder().statistic("p99").build());

using Amazon.CDK.AWS.Lambda;
using Aws.Cdk.Metrics.Facade.Alpha.Aws.Lambda;

Function fn;

var fnMetrics = LambdaMetrics.FromFunction(fn);

// Default statistic for Duration is Average
var defaultMetric = fnMetrics.Duration();

// Override statistic via MetricOptions
var p99Metric = fnMetrics.Duration(new MetricOptions { Statistic = "p99" });

import lambda "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws-samples/dummy/awscdkmetricsfacadealpha/awslambda"

var fn Function

fnMetrics := awscdkmetricsfacadealphaawslambda.LambdaMetrics_FromFunction(fn)

// Default statistic for Duration is Average
defaultMetric := fnMetrics.duration()

// Override statistic via MetricOptions
p99Metric := fnMetrics.duration(&MetricOptions{
	Statistic: jsii.String("p99"),
})

Unscoped Metrics

Unscoped metrics are not tied to a specific resource. They can be created with explicit dimensions or with no dimensions for account-wide metrics.

Unscoped Metrics Basic Usage

import { LambdaMetrics } from '@aws-cdk/metrics-facade-alpha/aws-lambda';
import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';

// Explicit dimensions
const fnMetrics = new LambdaMetrics.FunctionMetrics({
  functionName: 'my-function',
});
fnMetrics.errors();

// Per-resource dimensions (e.g. alias or version)
const resourceMetrics = new LambdaMetrics.ResourceMetrics({
  functionName: 'my-function',
  resource: 'prod',
});
resourceMetrics.provisionedConcurrencyUtilization();

// Account-wide metrics (no dimensions)
const accountMetrics = new LambdaMetrics.AccountMetrics();
accountMetrics.concurrentExecutions();
accountMetrics.unreservedConcurrentExecutions();

from aws_cdk.metrics_facade_alpha.aws_lambda import LambdaMetrics
import aws_cdk.aws_cloudwatch as cloudwatch


# Explicit dimensions
fn_metrics = LambdaMetrics.FunctionMetrics(
    function_name="my-function"
)
fn_metrics.errors()

# Per-resource dimensions (e.g. alias or version)
resource_metrics = LambdaMetrics.ResourceMetrics(
    function_name="my-function",
    resource="prod"
)
resource_metrics.provisioned_concurrency_utilization()

# Account-wide metrics (no dimensions)
account_metrics = LambdaMetrics.AccountMetrics()
account_metrics.concurrent_executions()
account_metrics.unreserved_concurrent_executions()

import aws.cdk.metrics.facade.alpha.aws.lambda.LambdaMetrics;
import software.amazon.awscdk.services.cloudwatch.*;


// Explicit dimensions
FunctionMetrics fnMetrics = new FunctionMetrics(new FunctionMetricsProps()
        .functionName("my-function")
        );
fnMetrics.errors();

// Per-resource dimensions (e.g. alias or version)
ResourceMetrics resourceMetrics = new ResourceMetrics(new ResourceMetricsProps()
        .functionName("my-function")
        .resource("prod")
        );
resourceMetrics.provisionedConcurrencyUtilization();

// Account-wide metrics (no dimensions)
AccountMetrics accountMetrics = new AccountMetrics();
accountMetrics.concurrentExecutions();
accountMetrics.unreservedConcurrentExecutions();

using Aws.Cdk.Metrics.Facade.Alpha.Aws.Lambda;
using Amazon.CDK.AWS.CloudWatch;


// Explicit dimensions
var fnMetrics = new LambdaMetrics.FunctionMetrics(new FunctionMetricsProps {
    FunctionName = "my-function"
});
fnMetrics.Errors();

// Per-resource dimensions (e.g. alias or version)
var resourceMetrics = new LambdaMetrics.ResourceMetrics(new ResourceMetricsProps {
    FunctionName = "my-function",
    Resource = "prod"
});
resourceMetrics.ProvisionedConcurrencyUtilization();

// Account-wide metrics (no dimensions)
var accountMetrics = new LambdaMetrics.AccountMetrics();
accountMetrics.ConcurrentExecutions();
accountMetrics.UnreservedConcurrentExecutions();

import "github.com/aws-samples/dummy/awscdkmetricsfacadealpha/awslambda"
import cloudwatch "github.com/aws/aws-cdk-go/awscdk"


// Explicit dimensions
fnMetrics := awscdkmetricsfacadealphaawslambda.LambdaMetrics.NewFunctionMetrics(&FunctionMetricsProps{
	functionName: jsii.String("my-function"),
})
fnMetrics.errors()

// Per-resource dimensions (e.g. alias or version)
resourceMetrics := awscdkmetricsfacadealphaawslambda.LambdaMetrics.NewResourceMetrics(&ResourceMetricsProps{
	functionName: jsii.String("my-function"),
	resource: jsii.String("prod"),
})
resourceMetrics.provisionedConcurrencyUtilization()

// Account-wide metrics (no dimensions)
accountMetrics := awscdkmetricsfacadealphaawslambda.LambdaMetrics.NewAccountMetrics()
accountMetrics.concurrentExecutions()
accountMetrics.unreservedConcurrentExecutions()

Available Metrics

Metrics are generated from the AWS CloudWatch metrics spec database. Common examples:

Lambda Metrics:

• invocations() - Function invocation count
• errors() - Function error count
• duration() - Function execution duration
• throttles() - Function throttle count
• concurrentExecutions() - Concurrent execution count

Import metrics from service-specific modules:

import { LambdaMetrics } from '@aws-cdk/metrics-facade-alpha/aws-lambda';

from aws_cdk.metrics_facade_alpha.aws_lambda import LambdaMetrics

import aws.cdk.metrics.facade.alpha.aws.lambda.LambdaMetrics;

using Aws.Cdk.Metrics.Facade.Alpha.Aws.Lambda;

import "github.com/aws-samples/dummy/awscdkmetricsfacadealpha/awslambda"

Types

Name	Kind	Summary