CloudWatch alarms can notify you when an AWS Lambda function starts failing, slows down, or runs into a capacity limit. A useful alarm matches the metric to a service objective, uses the right statistic and dimensions, and has a clear response. This guide covers the standard Lambda metrics, threshold and missing-data choices, SNS notifications, and a concrete AWS CLI example.

  • Use Sum for invocation, error, and throttle counts; use Maximum for peak concurrency.
  • Use a duration percentile such as p95 when it matches a latency objective and there are enough invocations to make the statistic useful.
  • Decide what quiet periods mean before choosing how an alarm treats missing data.
  • Monitor asynchronous delivery and event-source backlogs with the metrics that apply to the trigger.

Lambda metrics to track

Lambda publishes standard function metrics in the AWS/Lambda CloudWatch namespace at one-minute intervals. These are aggregated service metrics, not per-invocation records. Long-running functions can take several minutes to report their metrics. In CloudWatch, select dimensions that match the scope you need: FunctionName aggregates a function's versions and aliases, while Resource and ExecutedVersion can help isolate a version or alias. See AWS's Lambda metric overview, guide to viewing metric dimensions, and our overview of Lambda metrics and dimensions.

Function calls

Invocations counts executions of your function code. It includes executions that succeed and those that return a function error. Requests rejected before the code runs, including throttled requests, are not included. Use Sum over the alarm period to count executions. This metric does not represent all requests to an application: for example, a Lambda handler can catch an error and return an HTTP 500 response while Lambda records a successful function execution.

Errors and error rates

Errors counts invocations that end with an error raised by your code or the Lambda runtime. It includes timeouts and runtime configuration errors, but not requests that Lambda rejects before invoking the function. Use Sum to count failed executions. For a rate, divide the sum of Errors by the sum of Invocations for the same period and dimensions; do not divide their averages. This measures Lambda execution errors, not every failed business request: a handler can catch a problem and return an HTTP 5xx response while Lambda records a successful execution. Track application outcomes with an application metric or the relevant API service metric.

CloudWatch metric math drops a datapoint when an expression divides by zero. Guard a zero-valued denominator in a percentage expression, for example IF(invocations > 0, 100 * errors / invocations, 0), where errors and invocations are IDs for metric queries. When an Invocations datapoint has a value of zero, this expression returns zero percent; when the metric has no datapoint, IF drops that timestamp instead. Decide whether a quiet function is healthy: for a scheduled or continuously serving function, monitor an expected heartbeat or request signal separately.

Execution time

Duration is the time in milliseconds spent processing an event after initialization. It does not include cold-start time or time spent by a caller waiting outside the function. A timeout is counted by Errors; Duration is not a measure of end-to-end request latency. Use Average to see broad changes, Maximum to spot the slowest recorded value in a period, or a percentile such as p95 to follow a latency objective without letting one outlier dominate. Set the threshold from your service objective and function timeout, and make sure the period has enough invocations for the percentile to be useful.

Throttling events

Throttles counts requests Lambda rejects when execution capacity is unavailable. A throttled request does not count as an Invocation or an Error. Use Sum to count rejections, then inspect concurrency limits, scaling behavior, and the event source's retry policy before changing capacity.

Concurrent executions

ConcurrentExecutions measures function instances processing events at the same time. Use Maximum to compare peak concurrency with the function's reserved concurrency or the account's regional quota. There is no universal percentage that is safe for every workload; set a warning level from the capacity needed to absorb expected bursts and the time available to respond.

Asynchronous failures and delivery

For asynchronous invocations, AsyncEventAge can show how long queued events wait before execution, and AsyncEventsDropped counts events dropped without successful execution after expiry or retry exhaustion, among other causes. If you configure an on-failure destination or dead-letter queue, monitor DestinationDeliveryFailures or DeadLetterErrors for failed delivery to that destination. These delivery metrics do not replace Errors, which shows function failures. Asynchronous invocation settings and event-source mappings have different retry and destination behavior; for SQS triggers, also monitor queue age and the queue's own redrive policy. Check AWS's Lambda metric definitions and asynchronous error-handling settings for the trigger you use.

Memory use and cold starts

Memory usage and cold-start details are not standard metrics in the AWS/Lambda namespace. The function's CloudWatch REPORT logs include fields such as Max Memory Used and Init Duration; see AWS's Lambda log reference. CloudWatch Lambda Insights adds a separate LambdaInsights namespace with metrics such as memory_utilization and init_duration, and its performance events include a cold_start field. Enable the Insights extension before creating alarms on those metrics. See our Lambda Insights guide for its metrics and setup requirements.

Set up Lambda alarms

Choose an alarm only after deciding what a responder should do when it fires. Start with a customer-facing service objective, an accepted failure condition, or a tested capacity boundary. Historical CloudWatch data helps you understand normal traffic and variation, but it does not set an acceptable threshold on its own.

Select the metric and dimensions

  1. Open CloudWatch in the AWS Region where the function runs, then choose Alarms and Create alarm.
  2. Choose Select metric, open AWS/Lambda, and select the dimension that matches your scope, such as FunctionName for all versions or Resource for a particular alias or version.
  3. Select the metric. Confirm the function, namespace, and dimensions in the graph before continuing; a different dimension set identifies a different metric.

Match the alarm to the service condition

  • Function execution failures: Use Errors with Sum. Set the allowed failure count from the service's tolerance; any failure may matter for a critical job.

  • Failure rate at meaningful traffic: Use metric math over Errors and Invocations. Choose the threshold from the error budget or service objective, with explicit zero-traffic behavior.

  • Slow function processing: Use Duration, often p95, in milliseconds. Choose the threshold from the latency objective and function timeout.

  • Rejected requests or capacity pressure: Use Throttles with Sum, or ConcurrentExecutions with Maximum. Choose the threshold from trigger behavior, concurrency limits, and the capacity needed for bursts.

  • Events lost or unable to reach a failure handler: Use AsyncEventsDropped, DestinationDeliveryFailures, or DeadLetterErrors with Sum, as appropriate for the invocation source. Choose the threshold from its delivery and recovery requirements.

These are starting points, not fixed thresholds. For more on choosing a useful threshold, period, and missing-data behavior, see our guide to CloudWatch alarm conditions and evaluation.

Set the period and evaluation condition

Choose a period that matches Lambda's one-minute metric cadence and the time in which you need to respond. The period groups metric data into one datapoint. EvaluationPeriods is N, the number of recent datapoints CloudWatch evaluates; DatapointsToAlarm is M, the number that must breach. A 2-of-3 condition with one-minute periods triggers when two of the three datapoints breach; they do not have to be consecutive. It reduces reactions to a single brief spike but can take longer to alert than a 1-of-1 condition. Long-running invocations can also delay metric publication, so an alarm is not a real-time execution trace.

Choose a missing-data policy that reflects how the metric is emitted. For an error-count alarm, notBreaching is often appropriate when no datapoint means no errors; if the function is expected to run, use a separate heartbeat or canary to detect silence. A metric alarm's default is missing, which can lead to INSUFFICIENT_DATA when there are no usable datapoints. CloudWatch can also use older real datapoints in its evaluation range before applying the configured missing-data policy. See AWS's missing-data evaluation guide.

Send alarm notifications with SNS

Choose an Amazon SNS topic as the alarm action for the states that need attention, usually ALARM and sometimes OK for recovery. Subscribe an email address, SMS endpoint, or application to the topic. An email subscription must be confirmed before it can receive notifications. The topic's resource policy must allow CloudWatch to publish; when writing a policy, restrict the service principal with the alarm's source ARN and account. CloudWatch can create and configure a topic during alarm creation when you have the required permissions. The alarm and its Lambda metric are regional, and the SNS action is an ARN that includes a Region; this example uses us-east-1 for both. For workloads in multiple Regions, create and review alarm and notification routing in each Region. See AWS's SNS alarm notification instructions and topic policy example.

Create an alarm with the AWS CLI

This command creates or updates a function-wide alarm for errors. Before running it, configure the AWS CLI for the function's Region, use credentials allowed to create or update CloudWatch alarms, and replace the example function, account ID, topic, and Region with resources you own. The SNS topic must already exist and permit CloudWatch to publish; confirm the subscription if it uses email. The command uses a one-minute period and a 2-of-3 rule: two one-minute error counts greater than zero trigger the alarm.

aws cloudwatch put-metric-alarm \
  --region us-east-1 \
  --alarm-name "demo-orders-handler-errors" \
  --namespace "AWS/Lambda" \
  --metric-name "Errors" \
  --dimensions "Name=FunctionName,Value=orders-handler" \
  --statistic "Sum" \
  --period 60 \
  --evaluation-periods 3 \
  --datapoints-to-alarm 2 \
  --threshold 0 \
  --comparison-operator "GreaterThanThreshold" \
  --treat-missing-data "notBreaching" \
  --alarm-actions "arn:aws:sns:us-east-1:123456789012:ops-alerts"

The dimension selects the aggregate function metric. Change it if the alarm should follow one alias or version instead. The example omits --unit, following AWS's recommendation to avoid filtering on a unit that the metric does not publish. A unit selection filters the datapoints evaluated; it does not convert their values. Review the alarm graph and its state history after creation, and confirm the SNS subscription and topic policy if a state-change notification does not arrive. See the AWS CLI put-metric-alarm reference and CloudWatch PutMetricAlarm unit guidance.

Use metric math and anomaly detection carefully

Metric math for ratios

Metric math lets one alarm evaluate a derived time series, such as an error percentage. Give each metric query a short ID, use the same period and dimensions, and guard against a zero denominator. For example, IF(invocations > 0, 100 * errors / invocations, 0) yields a percentage from 0 to 100. Set a threshold such as 2 only if it represents the service's chosen 2% objective; it is not a general Lambda recommendation. The expression cannot tell whether a quiet period is healthy or whether expected traffic or telemetry stopped, so monitor expected activity separately when that distinction matters. See AWS's CloudWatch metric math reference.

Anomaly detection for changing traffic

CloudWatch anomaly detection models historical behavior and draws a band around an expected metric value. It can help with metrics whose normal level changes predictably by hour or day. Review the band against the service objective before paging on a deviation: historical behavior can include unhealthy periods, and an unusual value is not automatically customer impact. See AWS's anomaly detection guide.

Combine signals at the right layer

Use metric math to combine metric values into one time series, such as the guarded percentage described above. A CloudWatch composite alarm combines the states of existing alarms with Boolean logic. For example, it can notify only when a Lambda error alarm and a downstream-service alarm are both in ALARM. Keep each underlying alarm useful on its own and choose a composite only when the combination changes the response. See AWS's composite alarm guide.

Review and troubleshoot alarms

Set thresholds from evidence

Review metric graphs alongside service objectives and representative traffic. A function's acceptable error rate, tail latency, or concurrency headroom depends on its callers, retry behavior, and failure impact. Do not copy a percentage or regional quota fraction across functions without checking those conditions.

Check the alarm inputs and action

  • Confirm the namespace, metric name, dimensions, statistic, period, and unit describe the intended time series.
  • Compare the datapoints with the threshold and M-of-N setting; check whether long-running invocations delayed metric publication.
  • Review the missing-data choice, especially when a function receives traffic intermittently.
  • Check that an email subscriber confirmed the SNS subscription, the topic policy permits publication, and the action is configured for the state transition you expect.
  • Use Lambda logs or Insights performance events to investigate a metric change; aggregate alarm metrics do not explain an individual invocation.

Validate in a non-production setup

Check notification delivery with a test SNS message and verify the alarm configuration against a test function or test metric before relying on it for production response. Avoid forcing failures in a production function just to test an alarm. Confirm the threshold, state action, recipient, and recovery behavior with the team that owns the service.

Summary

Start with the metric that represents the failure you need to catch: Errors for failed executions, Throttles for rejected requests, Duration for function processing time, concurrency metrics for capacity, and async delivery or event-source metrics for backlogs and lost events. Use Sum for counts, Maximum for peak concurrency, and a latency percentile only when its sample volume supports the decision. Set periods, missing-data behavior, and thresholds from the workload, then route state changes to an owner who can act.