CloudConsole

CloudWatch alarm: Kinesis SubscribeToShardEvent.MillisBehindLatest

Updated 16 November 2026 · How we write and check guides

Short answer

Alarm on AWS/Kinesis SubscribeToShardEvent.MillisBehindLatest for a StreamName and ConsumerName pair, Average over 60 seconds, above your lag tolerance for 5 of 5 minutes. It is the enhanced fan-out equivalent of iterator age: how many milliseconds the records being pushed to that consumer are behind the tip of the stream.

Chart of the SubscribeToShardEvent.MillisBehindLatest alarm: Average per 1-minute period, ALARM when 5 of 5 datapoints are…
How the recommended alarm evaluates, with AWS's settings from this page and the page's example threshold. The metric values are illustrative.

What it measures, and how it differs from iterator age

Enhanced fan-out consumers do not poll. They call SubscribeToShard and Kinesis pushes SubscribeToShardEvent messages over an HTTP/2 connection. Each event carries MillisBehindLatest, and CloudWatch aggregates it per stream and registered consumer. Because each consumer has its own dimension, you can alarm on the one that matters without other readers diluting the figure.

GetRecords.IteratorAgeMilliseconds covers polling consumers. If a stream has both kinds, you need both alarms.

A subscription lasts at most five minutes before the consumer must call SubscribeToShard again. The KCL handles that; custom clients that forget to renew, or renew slowly, show a lag spike every few minutes.

Recommended alarm settings

SettingRecommended value
NamespaceAWS/Kinesis
MetricSubscribeToShardEvent.MillisBehindLatest
DimensionsStreamName, ConsumerName
StatisticAverage
ThresholdDepends on your situation (your lag tolerance in milliseconds)
Period60 seconds
Datapoints to alarm5
Evaluation periods5
Comparison operatorGreaterThanThreshold

Choosing the threshold

  1. Decide the business tolerance. How stale can the consumer's output be? For a live dashboard maybe 30 seconds; for an archiver, an hour.
  2. Look at two weeks of Average values to see the normal pattern, including subscription renewals and deploys.
  3. Cap it by retention. Stay well below half the stream's retention period so you are warned long before data expires.
  4. Set the threshold to the business tolerance if history is comfortably below it; otherwise fix the consumer first.

Because the statistic is Average, one lagging shard can be hidden by many healthy ones. If shards are unevenly loaded, add an alarm using Maximum.

Create the alarm

aws cloudwatch put-metric-alarm \
  --alarm-name kinesis-clickstream-analytics-lag \
  --alarm-description "analytics-efo consumer more than 60s behind for 5 minutes" \
  --namespace AWS/Kinesis \
  --metric-name SubscribeToShardEvent.MillisBehindLatest \
  --dimensions Name=StreamName,Value=clickstream Name=ConsumerName,Value=analytics-efo \
  --statistic Average \
  --period 60 \
  --evaluation-periods 5 \
  --datapoints-to-alarm 5 \
  --threshold 60000 \
  --comparison-operator GreaterThanThreshold \
  --alarm-actions arn:aws:sns:eu-west-2:123456789012:oncall-alerts

60,000 ms is an example for a near-real-time consumer.

When it fires

  1. Transient or sustained? A spike that clears is often a slow downstream call or a consumer restart. A steady climb means the consumer cannot keep up.
  2. Look for blocking calls in the record handler: synchronous writes to a database or API per record are the most frequent cause. Batch them or make them asynchronous.
  3. Check consumer resources at peak: CPU, memory and garbage collection on the hosts or containers running the consumer.
  4. Increase parallelism by adding shards (each shard is processed independently) and adding consumer workers to match.

If the alarm fires for one consumer only while others on the same stream are fine, the stream is not the problem: compare that consumer's deploys and resources with the healthy ones.

Questions

What is MillisBehindLatest in Kinesis?

The number of milliseconds between the records delivered to an enhanced fan-out consumer and the newest record in the shard. Zero means the consumer is caught up.

Why does MillisBehindLatest spike every five minutes?

Subscriptions expire after five minutes and must be renewed. A consumer that is slow to resubscribe briefly falls behind each time.

When this happens away from your desk

Consumer lag is the kind of alarm where the trend matters more than the number. CloudConsole, a phone app for AWS, is built to let you look at both from your phone before deciding to act.

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