Stacktape alarms monitor CloudWatch metrics for your deployed resources and fire when a threshold is breached. Define alarms on individual resources in your stack configuration and deploy the stack to apply changes. The Stacktape Console shows alarm state and history. When an alarm fires, it sends to its configured notificationChannels and opens an incident, which Console notification rules can route to alert channels.
When to use
Set up alarms when you need automated alerting on resource health — error rates, latency, CPU usage, storage pressure, or queue depth. Alarms are the primary way to get notified before a problem becomes an outage.
Common starting points:
- Lambda error rate — catch deployment regressions or upstream failures within minutes.
- Database CPU and free storage — prevent saturation before it causes connection timeouts.
- API error rate — detect HTTP 5xx spikes across your API gateway or load balancer.
- SQS queue depth — spot consumer backlog before messages start expiring.
For production stages, define at least one error-rate alarm per public-facing resource and one storage/CPU alarm per database. Keep these alarms in version control with each stack so threshold changes are reviewed and deployed with your code.
When NOT to use
Alarms are not the right tool for every monitoring need:
- Debugging a specific request — use logs and the
stacktape logsCLI command instead. - Trend analysis over weeks — use metrics dashboards in the Console for visual exploration.
- Tracking application-level errors — error tracking automatically groups and deduplicates runtime errors from your code. Alarms operate on aggregate CloudWatch metrics, not individual error instances.
- Cost alerting — use budgets to get notified when spend crosses a threshold.
Supported resources
Stacktape supports inline alarms on five resource types. Each resource accepts a specific set of trigger types:
| Resource | Config property | Accepted alarm triggers |
|---|---|---|
| Lambda function | alarms | lambda-error-rate, lambda-duration |
| Relational database | alarms | database-cpu-utilization, database-connection-count, database-read-latency, database-write-latency, database-free-storage, database-free-memory |
| HTTP API Gateway | alarms | http-api-gateway-error-rate, http-api-gateway-latency |
| Application Load Balancer | alarms | application-load-balancer-error-rate, application-load-balancer-unhealthy-targets, application-load-balancer-custom |
| SQS queue | alarms | sqs-queue-received-messages-count, sqs-queue-not-empty |
Trigger types
Lambda function triggers
| Trigger type | Threshold property | Unit | Default statistic | Default comparison |
|---|---|---|---|---|
lambda-error-rate | thresholdPercent | % | n/a | GreaterThanThreshold |
lambda-duration | thresholdMilliseconds | ms | avg | GreaterThanThreshold |
Relational database triggers
| Trigger type | Threshold property | Unit | Default statistic | Default comparison |
|---|---|---|---|---|
database-cpu-utilization | thresholdPercent | % | avg | GreaterThanThreshold |
database-connection-count | thresholdCount | count | avg | GreaterThanThreshold |
database-read-latency | thresholdSeconds | s | avg | GreaterThanThreshold |
database-write-latency | thresholdSeconds | s | avg | GreaterThanThreshold |
database-free-storage | thresholdMB | MB | min | LessThanThreshold |
database-free-memory | thresholdMB | MB | avg | LessThanThreshold |
For threshold-based triggers that expose comparisonOperator, the default is GreaterThanThreshold, except database-free-storage and database-free-memory, which default to LessThanThreshold — the alarm fires when the metric drops below the threshold.
HTTP API Gateway triggers
| Trigger type | Threshold property | Unit | Default statistic | Default comparison |
|---|---|---|---|---|
http-api-gateway-error-rate | thresholdPercent | % | n/a | GreaterThanThreshold |
http-api-gateway-latency | thresholdMilliseconds | ms | avg | GreaterThanThreshold |
Application Load Balancer triggers
| Trigger type | Threshold property | Unit | Default statistic | Default comparison |
|---|---|---|---|---|
application-load-balancer-error-rate | thresholdPercent | % | n/a | GreaterThanThreshold |
application-load-balancer-unhealthy-targets | thresholdPercent | % | n/a | GreaterThanThreshold |
application-load-balancer-custom | threshold (+ metric) | varies | avg | GreaterThanThreshold |
The application-load-balancer-custom trigger lets you alarm on additional ALB CloudWatch metrics beyond the built-in error-rate and unhealthy-targets triggers. See the API reference for supported properties.
The application-load-balancer-unhealthy-targets trigger also accepts an optional onlyIncludeTargets array to scope monitoring to specific container services behind the load balancer.
SQS queue triggers
| Trigger type | Threshold property | Unit | Default statistic | Default comparison |
|---|---|---|---|---|
sqs-queue-received-messages-count | thresholdCount | count | avg | GreaterThanThreshold |
sqs-queue-not-empty | (none) | — | — | — |
The sqs-queue-not-empty trigger has no configurable threshold — it fires whenever the queue has any unprocessed messages (visible, in-flight, messages received, or messages sent).
Customizing comparison and statistic
Most triggers accept two optional overrides:
comparisonOperator— how the metric is compared to the threshold. Options:GreaterThanThreshold,GreaterThanOrEqualToThreshold,LessThanThreshold,LessThanOrEqualToThreshold. The default varies by trigger type (see tables above).statistic— how metric values within each evaluation period are aggregated. Options:avg,min,max,sum,p90,p95,p99. Available on triggers that aggregate over time (duration, latency, counts, utilization, storage, memory). Error-rate triggers compute the ratio directly and don't expose a statistic override.
Defining alarms on resources
Stacktape alarms are defined inline on individual resources using the alarms property. Each alarm specifies a trigger (what to monitor and the threshold) and optionally an evaluation window and notificationChannels.
Lambda function alarms
A Lambda function accepts lambda-error-rate and lambda-duration triggers. The following example fires when more than 5% of invocations fail:
Database alarms
A relational database supports six trigger types covering CPU, storage, memory, connections, and I/O latency. The following example combines a CPU alarm with a free-storage alarm and tunes the evaluation window to avoid firing on brief spikes:
In this example, the CPU alarm evaluates three 5-minute periods and only fires if at least two of them breach 80%. The free-storage alarm uses the defaults (one 60-second period, fires after a single breached period) — appropriate for storage pressure that you want to catch right away.
Multiple alarms with notifications
This example shows a Lambda function with two alarms, each sending notifications to a Slack channel when triggered:
The description property adds context to notification messages. The statistic: 'p95' override on the duration alarm fires only when the 95th percentile exceeds the threshold, filtering out occasional slow invocations.
Evaluation windows
Stacktape alarm evaluation windows control how CloudWatch evaluates the metric before firing the alarm. The evaluation property prevents short-lived spikes from triggering false alerts while still catching sustained problems.
Three settings control the evaluation:
| Property | Default | Description |
|---|---|---|
period | 60 | Duration of one evaluation window in seconds. Must be a multiple of 60. |
evaluationPeriods | 1 | How many recent periods to look at. |
breachedPeriods | 1 | How many of those periods must breach the threshold to fire. Must be ≤ evaluationPeriods. |
How it works: At the end of each period, CloudWatch checks whether the metric breached the threshold during that period. If breachedPeriods out of the last evaluationPeriods periods are in breach, the alarm fires.
Example: With period: 300, evaluationPeriods: 5, breachedPeriods: 3, CloudWatch looks at the last 25 minutes (5 × 300s). If the threshold was breached in at least 3 of those 5 periods, the alarm fires. This pattern catches sustained issues while ignoring isolated spikes.
For production error-rate alarms, start with evaluationPeriods: 3 and breachedPeriods: 2 at a 60-second period. This gives you a 3-minute detection window that filters out single-period noise while still alerting within minutes.
For database storage alarms, the defaults (period: 60, evaluationPeriods: 1, breachedPeriods: 1) are usually appropriate — you want to know immediately when storage is running low.
Notification targets
Stacktape alarms can send notifications to one or more targets when they fire and when they recover. Configure the notificationChannels array on each alarm to specify where alerts are delivered. Supported target types include MS Teams, Slack, email, Discord, and webhooks.
Inline targets (slack, ms-teams, discord, email and webhook) are sent by the stack's own service Lambda, from your AWS account. The Lambda reads $Secret and secure SSM values when it sends the notification. Tokens, webhook URLs, signing secrets and headers are never sent to Stacktape. Email goes through Amazon SES in your account from the sender address. Microsoft Teams, Discord and webhook receivers get the same request format as from a Console alert channel. A webhook request carries the alarm's EventBridge event ID as id, so a receiver can drop a repeated delivery.
Each target receives one message when the alarm fires and one when it returns to OK after firing. A new alarm's first evaluation to OK sends nothing. If a target fails, the Lambda retries it without resending the targets that already received the message. Muting an incident in the Console does not silence inline targets, because the Console does not deliver them.
To reuse a named Console alert channel, add a console-channel reference to the alarm's notificationChannels. The Console delivers console-channel and slack-app targets with the credentials it keeps:
A firing alarm also opens an incident. Configure notification rules to route incident alerts to your team. Choose the delivery paths you need to avoid duplicate notifications.
Alarm description
Use the optional description property on an alarm to include a custom message in notification messages and the AWS console. This is helpful when you have multiple alarms on the same resource — the description makes it clear what the alarm means without looking up the config.
History tracking
The includeInHistory property controls whether alarm state changes should appear in monitoring history. It defaults to true. Set it to false on noisy development-stage alarms that would clutter the history view. Such an alarm is not reported to the Console, so it opens no incident. Its inline targets are still notified. console-channel and slack-app targets need history, and the deploy refuses an alarm that combines them with includeInHistory: false.
What leaves your AWS account
When an alarm with history changes state, the stack's service Lambda sends the Console the alarm event: the alarm name and trigger type, the project, stage and region, the new state and its time, the alarm's description, ARN and condition (comparison, statistic and unit), the stack name, the affected resource with its AWS console link, a link to the alarm, and the EventBridge event ID. It also sends the console-channel names and resolved slack-app channel IDs, which the Console delivers. Inline targets and their settings stay in your account.
Migrating legacy Console alarm rules
The Console no longer creates or edits alarm rules. Existing rules appear under Legacy alarm rules on the Alarms page. They keep applying to matching deployments until the stack defines its alarms in configuration.
Run stacktape alarm export to print those rules as config entries, including their project and stage scope. Add each entry to the alarms list of every resource it should monitor, preserve stage-specific behavior with stage-based configuration, and deploy each affected stage. Verify the resulting alarms before deleting the legacy rule in the Console.
disabledGlobalAlarms excludes named legacy rules from a resource while you migrate. For new alarms, edit the resource's alarms list directly.
Viewing alarm states
CLI
Use stacktape alarm list to inspect alarms from the CLI. See the CLI reference for flags and output details.
INSUFFICIENT_DATA typically means the resource hasn't produced enough metric data yet — common right after deployment or for resources with low traffic. It does not indicate a configuration error.
Console
The Console's Alarms page shows deployed alarms and their states across projects and stages. Open an alarm to inspect its state history. Configure thresholds and evaluation windows in the stack config, then deploy to apply them.
Alarms as event triggers
Stacktape alarm state changes can be used as event sources for Lambda functions, enabling automated remediation workflows. See alarms as triggers for configuration details.
API reference
AlarmDefinitionAlarms FAQ
How much do CloudWatch alarms cost?
AWS CloudWatch charges per alarm-metric per month. Stacktape alarms use standard resolution (periods must be multiples of 60 seconds). For most stacks, alarm costs are a small fraction of overall compute and database spend. See managing costs for broader cost guidance.
Can I set different alarm thresholds for production vs development?
Yes. Use stage-based configuration in your TypeScript config to select thresholds or omit alarms for a stage, then deploy each affected stage.
How do I avoid false alarms from short traffic spikes?
Tune the evaluation property. Increase evaluationPeriods (how many periods to look at) and set breachedPeriods to require multiple periods in breach before firing. For example, evaluationPeriods: 5 with breachedPeriods: 3 means the threshold must be breached in at least 3 of the last 5 periods. Increasing period from 60 to 300 seconds also smooths out short spikes by aggregating metric data over a wider window.
Where do I change an alarm rule?
Edit the resource's alarms list in the stack configuration and deploy. If the alarm comes from a legacy Console rule, export it into configuration first.
Can I alarm on custom CloudWatch metrics from my application?
Custom application-level metrics emitted via the CloudWatch SDK are not directly supported as alarm triggers in the Stacktape config. For each resource type, Stacktape provides a fixed set of trigger types covering the most critical metrics. The one exception is the application-load-balancer-custom trigger, which lets you alarm on any supported ALB CloudWatch metric by specifying the metric name and a threshold — see the API reference for supported properties.
How do I test that my alarms work?
Deploy a stage with alarms configured and use stacktape alarm list to verify the alarms were created. To trigger a test alarm, temporarily set a threshold that your current traffic would breach (e.g. thresholdPercent: 0 on an error-rate alarm) and wait for the evaluation period to elapse. Check your notification target (Slack, email, etc.) for the alert, then restore the real threshold.
When should I use alarms vs error tracking?
Alarms monitor aggregate CloudWatch metrics (error rates, CPU, latency) and fire based on thresholds you define. Error tracking automatically detects, groups, and deduplicates individual runtime errors from your application code. Use alarms for infrastructure-level health monitoring and error tracking for application-level errors. Most production stacks benefit from both — alarms catch broad degradation while error tracking catches specific bugs.