# 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).
---