serverless-timeout-alarms/README.md

Serverless plugin to add CloudWatch metric and alarm for Lambda timeouts

### serverless-timeout-alarms

Add CloudWatch metric filter and alarm for Lambda timeouts automatically during Serverless packaging.

- Creates a CloudWatch Logs metric filter that counts occurrences of timeout logs per function
- Adds a CloudWatch Alarm on that metric with configurable threshold/evaluation periods
- Supports global defaults and per-function overrides

### Installation

```bash
npm install -D serverless-timeout-alarms
```

### Usage

Add the plugin and configure global defaults in your `serverless.yml`:

```yaml
plugins:
  - serverless-timeout-alarms

custom:
  timeoutAlarm:
    enabled: true
    namespace: Serverless/LambdaTimeouts
    filterPattern: timeout
    threshold: 1
    period: 300
    evaluationPeriods: 1
    statistic: Sum
    treatMissingData: notBreaching
    # Optional: SNS topic ARN for alarm actions
    # alarmActionSnsTopic: arn:aws:sns:us-east-1:123456789012:alerts

functions:
  hello:
    handler: src/handler.hello
    # Optional per-function override
    timeoutAlarm:
      enabled: true
      threshold: 2
```

When you run `serverless package` (or `deploy`), the plugin will add the following resources for each enabled function:
- `AWS::Logs::MetricFilter` to count timeout log events
- `AWS::CloudWatch::Alarm` on that metric

Alarm names use the format: `[<stage>][<service>][<functionName>][TimeoutAlarm]`.

### Configuration

Global `custom.timeoutAlarm` and per-function `functions.<name>.timeoutAlarm` support:

- `enabled` (boolean, default: true)
- `namespace` (string, default: `Serverless/LambdaTimeouts`)
- `filterPattern` (string, default: `timeout`)
- `threshold` (number, default: 1)
- `period` (seconds, default: 300)
- `evaluationPeriods` (number, default: 1)
- `statistic` (Sum | Average | Maximum | Minimum | SampleCount; default: `Sum`)
- `treatMissingData` (notBreaching | breaching | ignore | missing; default: `notBreaching`)
- `alarmActionSnsTopic` (optional string: SNS topic ARN)

If `alarmActionSnsTopic` is omitted, the alarm is created without actions; you can attach actions later.

### Example metric name

For a service `my-api`, function `getItem`, stage `prod`:

`/lambda/my-api/getItem/prod/timeoutCount`

### Quick deploy

Build and deploy/package as usual with Serverless:

```bash
npx serverless deploy
# or
npx serverless package
```

### License

MIT