# API Reference ## Constructs ### LambdaFailureDetector CloudWatch failure detection for a Lambda function. Always creates platform `AWS/Lambda` `Errors` and `Throttles` alarms. Optionally creates DeadLetterErrors, DestinationDeliveryFailures, and IteratorAge alarms, plus one metric filter and alarm per {@link LogFailureFilter}. Does not create an SNS topic; pass {@link LambdaFailureDetectorAlarmProps.topic} to attach notifications. #### Initializers ```typescript import { LambdaFailureDetector } from 'lambda-failure-detector' new LambdaFailureDetector(scope: Construct, id: string, props: LambdaFailureDetectorProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | scope | constructs.Construct | - Parent construct. | | id | string | - Construct id. | | props | LambdaFailureDetectorProps | - Lambda, optional log group / retention / filters, and alarm settings. | --- ##### `scope`Required - *Type:* constructs.Construct Parent construct. --- ##### `id`Required - *Type:* string Construct id. --- ##### `props`Required - *Type:* LambdaFailureDetectorProps Lambda, optional log group / retention / filters, and alarm settings. --- #### Methods | **Name** | **Description** | | --- | --- | | toString | Returns a string representation of this construct. | | with | Applies one or more mixins to this construct. | | findLogFilterAlarm | Returns the log-filter alarm for the given filter id, or undefined when missing. | --- ##### `toString` ```typescript public toString(): string ``` Returns a string representation of this construct. ##### `with` ```typescript public with(mixins: ...IMixin[]): IConstruct ``` Applies one or more mixins to this construct. Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple `with()` calls if subsequent mixins should apply to added constructs. ###### `mixins`Required - *Type:* ...constructs.IMixin[] The mixins to apply. --- ##### `findLogFilterAlarm` ```typescript public findLogFilterAlarm(id: string): Alarm ``` Returns the log-filter alarm for the given filter id, or undefined when missing. ###### `id`Required - *Type:* string Same as {@link LogFailureFilter.id}. --- #### Static Functions | **Name** | **Description** | | --- | --- | | isConstruct | Checks if `x` is a construct. | --- ##### `isConstruct` ```typescript import { LambdaFailureDetector } from 'lambda-failure-detector' LambdaFailureDetector.isConstruct(x: any) ``` Checks if `x` is a construct. Use this method instead of `instanceof` to properly detect `Construct` instances, even when the construct library is symlinked. Explanation: in JavaScript, multiple copies of the `constructs` library on disk are seen as independent, completely different libraries. As a consequence, the class `Construct` in each copy of the `constructs` library is seen as a different class, and an instance of one class will not test as `instanceof` the other class. `npm install` will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the `constructs` library can be accidentally installed, and `instanceof` will behave unpredictably. It is safest to avoid using `instanceof`, and using this type-testing method instead. ###### `x`Required - *Type:* any Any object. --- #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | node | constructs.Node | The tree node. | | lambdaErrorsAlarm | aws-cdk-lib.aws_cloudwatch.Alarm | Fires when the Lambda `Errors` metric is non-zero. | | lambdaThrottlesAlarm | aws-cdk-lib.aws_cloudwatch.Alarm | Fires when the Lambda `Throttles` metric is non-zero. | | logFilterAlarms | LogFailureAlarm[] | Alarms for each log filter, in the same order as {@link LambdaFailureDetectorLogProps.filters}. | | alarmTopic | aws-cdk-lib.aws_sns.ITopic | SNS topic used for alarm actions, when configured. | | deadLetterErrorsAlarm | aws-cdk-lib.aws_cloudwatch.Alarm | Fires when `DeadLetterErrors` is non-zero, when opted in. | | destinationDeliveryFailuresAlarm | aws-cdk-lib.aws_cloudwatch.Alarm | Fires when `DestinationDeliveryFailures` is non-zero, when opted in. | | iteratorAgeAlarm | aws-cdk-lib.aws_cloudwatch.Alarm | Fires when stream `IteratorAge` reaches the configured threshold, when opted in. | | logGroup | aws-cdk-lib.aws_logs.ILogGroup | Log group used for log metric filters, when log filters are configured. | --- ##### `node`Required ```typescript public readonly node: Node; ``` - *Type:* constructs.Node The tree node. --- ##### `lambdaErrorsAlarm`Required ```typescript public readonly lambdaErrorsAlarm: Alarm; ``` - *Type:* aws-cdk-lib.aws_cloudwatch.Alarm Fires when the Lambda `Errors` metric is non-zero. --- ##### `lambdaThrottlesAlarm`Required ```typescript public readonly lambdaThrottlesAlarm: Alarm; ``` - *Type:* aws-cdk-lib.aws_cloudwatch.Alarm Fires when the Lambda `Throttles` metric is non-zero. --- ##### `logFilterAlarms`Required ```typescript public readonly logFilterAlarms: LogFailureAlarm[]; ``` - *Type:* LogFailureAlarm[] Alarms for each log filter, in the same order as {@link LambdaFailureDetectorLogProps.filters}. --- ##### `alarmTopic`Optional ```typescript public readonly alarmTopic: ITopic; ``` - *Type:* aws-cdk-lib.aws_sns.ITopic SNS topic used for alarm actions, when configured. --- ##### `deadLetterErrorsAlarm`Optional ```typescript public readonly deadLetterErrorsAlarm: Alarm; ``` - *Type:* aws-cdk-lib.aws_cloudwatch.Alarm Fires when `DeadLetterErrors` is non-zero, when opted in. --- ##### `destinationDeliveryFailuresAlarm`Optional ```typescript public readonly destinationDeliveryFailuresAlarm: Alarm; ``` - *Type:* aws-cdk-lib.aws_cloudwatch.Alarm Fires when `DestinationDeliveryFailures` is non-zero, when opted in. --- ##### `iteratorAgeAlarm`Optional ```typescript public readonly iteratorAgeAlarm: Alarm; ``` - *Type:* aws-cdk-lib.aws_cloudwatch.Alarm Fires when stream `IteratorAge` reaches the configured threshold, when opted in. --- ##### `logGroup`Optional ```typescript public readonly logGroup: ILogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.ILogGroup Log group used for log metric filters, when log filters are configured. Undefined when there are no log filters. --- ## Structs ### AlarmConfig CloudWatch alarm settings for failure metrics. Omitted fields keep the construct defaults (threshold 1, period 5 minutes, evaluationPeriods 1, treatMissingData `NOT_BREACHING`). `threshold` applies to sum metrics only; IteratorAge uses {@link PlatformMetricsOptions.iteratorAgeThreshold}. #### Initializer ```typescript import { AlarmConfig } from 'lambda-failure-detector' const alarmConfig: AlarmConfig = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | evaluationPeriods | number | Number of periods that must breach before the alarm fires. | | period | aws-cdk-lib.Duration | Metric period used by the alarm. | | threshold | number | Alarm threshold for sum metrics. | | treatMissingData | aws-cdk-lib.aws_cloudwatch.TreatMissingData | How missing datapoints are treated. | --- ##### `evaluationPeriods`Optional ```typescript public readonly evaluationPeriods: number; ``` - *Type:* number - *Default:* 1 Number of periods that must breach before the alarm fires. --- ##### `period`Optional ```typescript public readonly period: Duration; ``` - *Type:* aws-cdk-lib.Duration - *Default:* Duration.minutes(5) Metric period used by the alarm. --- ##### `threshold`Optional ```typescript public readonly threshold: number; ``` - *Type:* number - *Default:* 1 Alarm threshold for sum metrics. --- ##### `treatMissingData`Optional ```typescript public readonly treatMissingData: TreatMissingData; ``` - *Type:* aws-cdk-lib.aws_cloudwatch.TreatMissingData - *Default:* TreatMissingData.NOT_BREACHING How missing datapoints are treated. --- ### LambdaFailureDetectorAlarmProps Shared alarm settings for {@link LambdaFailureDetector}. The construct does not create an SNS topic. #### Initializer ```typescript import { LambdaFailureDetectorAlarmProps } from 'lambda-failure-detector' const lambdaFailureDetectorAlarmProps: LambdaFailureDetectorAlarmProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | config | AlarmConfig | Shared CloudWatch alarm settings for failure alarms. | | platformMetrics | PlatformMetricsOptions | Opt-in platform metrics beyond the standard `Errors` and `Throttles` alarms. | | topic | aws-cdk-lib.aws_sns.ITopic | SNS topic for all alarm actions. | --- ##### `config`Optional ```typescript public readonly config: AlarmConfig; ``` - *Type:* AlarmConfig - *Default:* threshold 1, period 5 minutes, evaluationPeriods 1, treatMissingData NOT_BREACHING Shared CloudWatch alarm settings for failure alarms. Applies to sum metrics (`Errors`, `Throttles`, opt-in counts, and log filters). IteratorAge uses `period` / `evaluationPeriods` / `treatMissingData` from this config, but its threshold comes from {@link PlatformMetricsOptions.iteratorAgeThreshold}. --- ##### `platformMetrics`Optional ```typescript public readonly platformMetrics: PlatformMetricsOptions; ``` - *Type:* PlatformMetricsOptions - *Default:* no additional platform metric alarms Opt-in platform metrics beyond the standard `Errors` and `Throttles` alarms. --- ##### `topic`Optional ```typescript public readonly topic: ITopic; ``` - *Type:* aws-cdk-lib.aws_sns.ITopic SNS topic for all alarm actions. When omitted, alarms are created without SNS actions. --- ### LambdaFailureDetectorLogProps Log group and log-based failure filters for {@link LambdaFailureDetector}. #### Initializer ```typescript import { LambdaFailureDetectorLogProps } from 'lambda-failure-detector' const lambdaFailureDetectorLogProps: LambdaFailureDetectorLogProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | filters | LogFailureFilter[] | Log-based failure filters. | | group | aws-cdk-lib.aws_logs.ILogGroup | Log group used for {@link LogFailureFilter} metric filters. | | retention | aws-cdk-lib.aws_logs.RetentionDays | Retention for the Lambda log group when the construct manages it. | --- ##### `filters`Optional ```typescript public readonly filters: LogFailureFilter[]; ``` - *Type:* LogFailureFilter[] - *Default:* no log-based alarms Log-based failure filters. Each entry creates a metric filter and alarm. --- ##### `group`Optional ```typescript public readonly group: ILogGroup; ``` - *Type:* aws-cdk-lib.aws_logs.ILogGroup Log group used for {@link LogFailureFilter} metric filters. Required only when you pass {@link LambdaFailureDetectorLogProps.filters} and want to use an existing group. When omitted with filters, the construct manages `/aws/lambda/` and applies {@link LambdaFailureDetectorLogProps.retention}. Do not set together with {@link LambdaFailureDetectorLogProps.retention}. --- ##### `retention`Optional ```typescript public readonly retention: RetentionDays; ``` - *Type:* aws-cdk-lib.aws_logs.RetentionDays - *Default:* RetentionDays.ONE_YEAR Retention for the Lambda log group when the construct manages it. Used when {@link LambdaFailureDetectorLogProps.filters} are set and {@link LambdaFailureDetectorLogProps.group} is omitted. Creates a `LogRetention` custom resource for `/aws/lambda/`. Do not set together with {@link LambdaFailureDetectorLogProps.group}. --- ### LambdaFailureDetectorProps Props for {@link LambdaFailureDetector}. #### Initializer ```typescript import { LambdaFailureDetectorProps } from 'lambda-failure-detector' const lambdaFailureDetectorProps: LambdaFailureDetectorProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | lambdaFunction | aws-cdk-lib.aws_lambda.IFunction | Lambda function whose platform failure metrics are alarmed. | | alarm | LambdaFailureDetectorAlarmProps | SNS topic, shared alarm settings, and opt-in platform metrics. | | log | LambdaFailureDetectorLogProps | Log group, retention, and log-based failure filters. | --- ##### `lambdaFunction`Required ```typescript public readonly lambdaFunction: IFunction; ``` - *Type:* aws-cdk-lib.aws_lambda.IFunction Lambda function whose platform failure metrics are alarmed. --- ##### `alarm`Optional ```typescript public readonly alarm: LambdaFailureDetectorAlarmProps; ``` - *Type:* LambdaFailureDetectorAlarmProps - *Default:* default alarm settings, no SNS actions, no extra platform metrics SNS topic, shared alarm settings, and opt-in platform metrics. --- ##### `log`Optional ```typescript public readonly log: LambdaFailureDetectorLogProps; ``` - *Type:* LambdaFailureDetectorLogProps - *Default:* platform alarms only; no log group is managed Log group, retention, and log-based failure filters. --- ### LogFailureAlarm Alarm created for one {@link LogFailureFilter}. #### Initializer ```typescript import { LogFailureAlarm } from 'lambda-failure-detector' const logFailureAlarm: LogFailureAlarm = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | alarm | aws-cdk-lib.aws_cloudwatch.Alarm | Alarm on the log metric filter sum. | | id | string | Same as {@link LogFailureFilter.id}. | --- ##### `alarm`Required ```typescript public readonly alarm: Alarm; ``` - *Type:* aws-cdk-lib.aws_cloudwatch.Alarm Alarm on the log metric filter sum. --- ##### `id`Required ```typescript public readonly id: string; ``` - *Type:* string Same as {@link LogFailureFilter.id}. --- ### LogFailureFilter One log-based failure signal for {@link LambdaFailureDetector}. Creates a CloudWatch Logs metric filter and an alarm on the resulting sum metric. #### Initializer ```typescript import { LogFailureFilter } from 'lambda-failure-detector' const logFailureFilter: LogFailureFilter = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | filterPattern | aws-cdk-lib.aws_logs.IFilterPattern | CloudWatch Logs filter pattern. | | id | string | Stable id used as the MetricFilter / Alarm construct id prefix (e.g. `InstanceStatusFailure` → `InstanceStatusFailureMetric`). | | metricName | string | Custom metric name for the metric filter. | | metricNamespace | string | Custom metric namespace for the metric filter. | --- ##### `filterPattern`Required ```typescript public readonly filterPattern: IFilterPattern; ``` - *Type:* aws-cdk-lib.aws_logs.IFilterPattern CloudWatch Logs filter pattern. Pass any {@link IFilterPattern}, including JSON field comparisons from `FilterPattern`. The pattern is not wrapped again. --- *Example* ```typescript FilterPattern.literal('"ResourceWaitFailed"') ``` ##### `id`Required ```typescript public readonly id: string; ``` - *Type:* string Stable id used as the MetricFilter / Alarm construct id prefix (e.g. `InstanceStatusFailure` → `InstanceStatusFailureMetric`). Must be unique among {@link LambdaFailureDetectorLogProps.filters}. --- ##### `metricName`Required ```typescript public readonly metricName: string; ``` - *Type:* string Custom metric name for the metric filter. --- ##### `metricNamespace`Required ```typescript public readonly metricNamespace: string; ``` - *Type:* string Custom metric namespace for the metric filter. --- ### PlatformMetricsOptions Opt-in platform metrics beyond the standard `Errors` and `Throttles` alarms. `Errors` and `Throttles` are always created. Enable the flags below when the function uses a dead-letter queue, on-failure destination, or stream source. #### Initializer ```typescript import { PlatformMetricsOptions } from 'lambda-failure-detector' const platformMetricsOptions: PlatformMetricsOptions = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | deadLetterErrors | boolean | Create an alarm on the `AWS/Lambda` `DeadLetterErrors` sum metric. | | destinationDeliveryFailures | boolean | Create an alarm on the `AWS/Lambda` `DestinationDeliveryFailures` sum metric. | | iteratorAge | boolean | Create an alarm on the `AWS/Lambda` `IteratorAge` maximum metric. | | iteratorAgeThreshold | number | Threshold in milliseconds for the IteratorAge alarm. | --- ##### `deadLetterErrors`Optional ```typescript public readonly deadLetterErrors: boolean; ``` - *Type:* boolean - *Default:* false Create an alarm on the `AWS/Lambda` `DeadLetterErrors` sum metric. --- ##### `destinationDeliveryFailures`Optional ```typescript public readonly destinationDeliveryFailures: boolean; ``` - *Type:* boolean - *Default:* false Create an alarm on the `AWS/Lambda` `DestinationDeliveryFailures` sum metric. --- ##### `iteratorAge`Optional ```typescript public readonly iteratorAge: boolean; ``` - *Type:* boolean - *Default:* false Create an alarm on the `AWS/Lambda` `IteratorAge` maximum metric. Intended for functions with stream event sources (Kinesis, DynamoDB Streams). --- ##### `iteratorAgeThreshold`Optional ```typescript public readonly iteratorAgeThreshold: number; ``` - *Type:* number - *Default:* 60000 Threshold in milliseconds for the IteratorAge alarm. Used only when {@link PlatformMetricsOptions.iteratorAge} is true. Shared {@link AlarmConfig.threshold} does not apply (that value is for sum counts). ---