CloudConsole

API Gateway MessageCount alarm per WebSocket route

Updated 17 November 2026 · How we write and check guides

Short answer

This alarm narrows the WebSocket low-traffic check to a single route using the ApiId, Stage and Route dimensions, which require detailed metrics on the stage. It fires when the SampleCount of MessageCount for that route stays below your threshold for 10 of 10 one-minute periods.

Chart of the MessageCount alarm: SampleCount per 1-minute period, ALARM when 10 of 10 datapoints are < 10
How the recommended alarm evaluates, with AWS's settings from this page and the page's example threshold. The metric values are illustrative.

Route-level versus stage-level

On a WebSocket API most volume often comes from one chatty route, such as a heartbeat or presence update. If the route that carries real work (say placeOrder or sendMessage) breaks, the stage-level MessageCount alarm barely moves. The per-route alarm watches that route alone.

Use the stage alarm whenUse the route alarm when
You want one cheap outage signal for the whole APIA specific route carries business-critical messages
Detailed metrics are offDetailed metrics are on (extra cost per route)
Routes have similar volumeOne noisy route would hide a failure in another

Recommended settings

SettingValue
NamespaceAWS/ApiGateway
MetricMessageCount
DimensionsApiId, Stage, Route
StatisticSampleCount
Period60 seconds
Datapoints to alarm10
Evaluation periods10
Comparison operatorLessThanThreshold
ThresholdDepends on your situation: from that route's historical volume

As listed in the CloudWatch recommended alarms reference. The Route value is the route key, for example sendMessage, or the reserved keys $connect, $disconnect and $default.

Choosing a per-route threshold

Routes driven by user actions are far spikier than heartbeat routes, so a floor that works for the stage is wrong here. A method that copes with that:

  • Plot the route's one-minute counts against the stage's for a week.
  • If the route's share of stage traffic is stable (for example, sendMessage is always 10–15% of messages), a metric-math ratio alarm is more robust than a raw count.
  • If you stay with the raw count, set it under the route's lowest healthy minute and accept that it will only catch a near-complete stop.
  • Routes with idle minutes are poor candidates; use a longer period or a synthetic client that sends a test message every minute.

Create it

# Enable detailed metrics for all routes on the stage
aws apigatewayv2 update-stage --api-id w1x2y3z4a5 --stage-name prod \
  --default-route-settings DetailedMetricsEnabled=true
# Example floor of 10 messages per minute on the sendMessage route
aws cloudwatch put-metric-alarm \
  --alarm-name chat-ws-sendmessage-low \
  --namespace AWS/ApiGateway \
  --metric-name MessageCount \
  --dimensions Name=ApiId,Value=w1x2y3z4a5 Name=Stage,Value=prod Name=Route,Value=sendMessage \
  --statistic SampleCount \
  --period 60 \
  --evaluation-periods 10 \
  --datapoints-to-alarm 10 \
  --threshold 10 \
  --comparison-operator LessThanThreshold \
  --treat-missing-data breaching \
  --alarm-actions arn:aws:sns:eu-west-2:123456789012:ops-alerts \
  --region eu-west-2

When it fires

  1. Is the route still matched? Clients may have changed the field that the route selection expression reads (for instance renaming action), so their messages fall through to $default. A rising $default count at the same moment confirms it.
  2. Is the integration erroring? Check IntegrationError and ExecutionError for the route.
  3. Is the feature in use? Rule out a front-end change that hid or removed the feature that sends this message.
  4. Check route-level throttling settings; a very low route limit produces client errors instead of messages.

Questions

What is the Route dimension value for a WebSocket API?

The route key, such as sendMessage, or one of the reserved keys $connect, $disconnect and $default.

Why is my route-level MessageCount alarm empty?

Detailed metrics are probably not enabled on the stage, or the route has had no traffic since they were.

Should I alarm on $default traffic?

A sudden rise in $default can be more useful than a drop: it often means clients are sending messages that no longer match their intended route.

When this happens away from your desk

When a single WebSocket route breaks, the API looks fine at a glance. CloudConsole, a phone app for AWS, is built to show per-route alarms and message graphs on a phone so you can see which flow stopped.

Did it start after a deploy? What changed? on the app’s alarm screen lists the deploys and configuration changes from the hour before the alarm fired.

About the app → · Download on the App Store

Sources