Lambda Error Monitoring: Best Practices

Useful Lambda error monitoring starts with the invocation path. The CloudWatch Errors metric counts function or runtime errors; it does not count every unsuccessful business outcome, request rejected before the handler runs, or record-level failure that a batch handler reports as a normal response. Retries and recovery also depend on whether a caller invokes the function synchronously, Lambda queues an asynchronous event, or an event source mapping polls a queue or stream.

Use function metrics to detect a change, logs to explain an invocation, and source-specific metrics to see delivery or backlog problems. For a console and CLI walkthrough that creates an error-rate alarm and runs Logs Insights queries, see Monitor Lambda Errors with CloudWatch. For definitions and dimensions of the standard metrics, see AWS Lambda metrics in CloudWatch.

Monitor the invocation path, not just Errors

Classify the failure before choosing a signal

Lambda uses “function error” for an invocation in which the handler or runtime returns an error. An uncaught exception, timeout, or some configuration and runtime failures can increment Errors. If the handler catches an exception and returns normally, Lambda sees a successful function invocation even if the application logs an error or returns an HTTP 4xx or 5xx response. Emit an application metric or measure the response at the API boundary when those outcomes matter.

Throttling is separate. A request that Lambda rejects because concurrency is unavailable increments Throttles; it does not increment Invocations or Errors. A source may retry the request, delay it, or eventually drop it, so investigate the source and its delivery metrics as well as the function.

The distinction matters even for a batch handler. For SQS, an event source mapping retries only the records identified as failed when partial batch responses are enabled. With a FIFO queue, stop after the first failure and report that message plus every unprocessed message so the queue's order is preserved. For Kinesis and DynamoDB Streams, Lambda checkpoints at the earliest failed sequence number and can replay later records from that batch. In all these cases, the handler's partial-failure response is a normal function response, not a Lambda function error. Log or count record-level failures separately so a low Errors value does not conceal a poison message or repeated business failure. AWS describes the required configuration for SQS partial batch responses and stream partial batch responses.

Choose metrics that match the trigger

Lambda publishes standard service metrics in CloudWatch's AWS/Lambda namespace at one-minute intervals. They do not require additional permissions on the function's execution role. Use Sum for invocation and error counts, and Max for concurrency. Metric timestamps can precede the time a long invocation finishes, so allow for reporting delay during an incident. AWS maintains the current Lambda metric definitions.

Signal	What it tells you	What to check next
Invocations	Calls that reached the function code, including calls that returned function errors. Throttled and other rejected invocation requests are not included.	Traffic volume and the function, version, or alias dimension.
Errors	Invocations that returned a function or runtime error. This is not a count of handled application errors or failed records in a successful partial-batch response.	Request IDs, exception details, runtime logs, and the handler's error behavior.
Throttles	Requests rejected before function code ran because execution capacity was not available.	Concurrency, account and function limits, and source retry or backoff behavior.
Duration	Function processing time; it excludes initialization time.	Latency objectives, percentiles, downstream calls, and initialization fields in logs.
ConcurrentExecutions	Executions in flight.	Regional and reserved concurrency, traffic bursts, and downstream capacity.
AsyncEventAge, AsyncEventsDropped	Age of queued asynchronous events and events discarded without successful execution, for example after expiry or retry exhaustion.	Errors, Throttles, event age limits, retry settings, and the configured failure destination.
Source queue or stream metrics	Backlog and processing progress for an event source mapping. Examples include SQS oldest-message age and stream iterator age.	Batch size, visibility or retention, mapping errors, partial responses, and source-specific retry limits.
DeadLetterErrors, DestinationDeliveryFailures	DeadLetterErrors counts failed delivery to an asynchronous function's DLQ. DestinationDeliveryFailures counts failed delivery to a configured destination, including supported stream mappings. Both are delivery problems, not totals of function failures.	Destination type, permissions, resource configuration, and size limits.

For asynchronous invocations, a failure destination receives an invocation record with request and response context, while a function-level DLQ stores the original event. A stream event source mapping's on-failure destination receives failed source records. SQS redrive and dead-letter handling belong to the source queue. Check which payload the recovery process expects before configuring a destination; AWS compares asynchronous destinations and DLQs with SQS queue redrive settings.

For an approximate function error rate, compare the sum of Errors with the sum of Invocations over the same period: Errors / Invocations. Do not treat a zero or missing denominator as a healthy request. For batch sources, also measure record-level outcomes because one invocation can contain many records.

Add runtime telemetry when a specific question needs it

CloudWatch Lambda Insights adds runtime and execution-environment telemetry such as memory use and initialization details. It complements the standard AWS/Lambda metrics; it does not replace the function's error metrics or application logs. Enable it for functions where that additional data will help answer a concrete resource or startup question, then account for its extension, metrics, and log costs. Our guide explains Lambda Insights setup, metrics, and costs.

Connect metrics, logs, and alarms

In CloudWatch, select the AWS/Lambda namespace and choose dimensions that match the unit you operate: function, version, alias, or Region. A function-name graph can combine versions; inspect a version or alias separately when a rollout could be hiding a regression. Keep the Lambda function and CloudWatch view in the same Region.

Pair a metric with invocation logs. The function's execution role needs permission to write to CloudWatch Logs; the AWSLambdaBasicExecutionRole managed policy supplies the usual log-group, log-stream, and log-event permissions. A restricted or custom log-group setup may need a policy adjusted to that group. The role does not need extra permissions for Lambda's standard service metrics. See AWS's guidance for Lambda logging permissions and destinations.

Prefer structured JSON application logs when the runtime and logging method support them. Include the Lambda request ID, a safe business identifier, an error type, and a concise message. Do not log credentials, tokens, or entire event payloads by default. Logging an error is not the same as throwing it: record handled business failures in an application metric or log field if they need their own alarm. AWS documents JSON log formats and supported logging methods.

Make alarms reflect impact and recovery

Start with signals a responder can act on: function Errors, Throttles, an error rate tied to a service objective, and source backlog or event age where delivery delay matters. An absolute error-count alarm can catch a failure at low traffic; a rate alarm gives volume context. For the rate, use CloudWatch metric math over Errors and Invocations with the same dimensions and period. Do not copy a generic threshold such as one percent or a memory percentage without checking the workload and its acceptable impact.

Choose the evaluation window and number of breaching datapoints based on how quickly the team must respond and how much short-lived variation is acceptable. Decide what missing data means. For an event-driven error count or a rate expression with no invocations, notBreaching can avoid paging on idle periods; it also will not detect missing telemetry. If the function should receive traffic continuously, monitor expected invocations or a synthetic heartbeat separately. AWS explains missing-data treatment and metric math alarms.

Route notifications to an owner and test the full alarm action. CloudWatch can invoke a Lambda function as an alarm action, but its resource-based policy must allow the CloudWatch alarms service to invoke it; see AWS's guidance to invoke a Lambda function from an alarm. Use automation only for a bounded, retry-safe response; a function error by itself does not tell you whether to change memory, concurrency, or a downstream service.

Use Logs Insights to find the cause

Logs Insights helps search and aggregate records over a selected time range and log group. Start with application errors or Lambda platform messages, then correlate the request ID with the metric window. A count of matching log entries is not a guaranteed invocation error rate: applications can log more than once per invocation, catch errors, or report failures inside a successful batch response.

Build a monitoring practice around response

Use each tool for the question it answers

Use Lambda and source metrics to spot changing error volume, throttles, latency, and backlog. Use CloudWatch Logs to find the invocation or record that explains the change. Use distributed tracing when you need to follow a request across services; it complements these signals but does not replace the event source's delivery metrics.

Keep alerts actionable and low-noise

• Alert on a service objective, user-visible failure, supported capacity limit, or growing event backlog.
• Use count and rate together when a small absolute count or a traffic-relative percentage could each matter.
• Choose percentile latency alarms only when the period has enough samples to make that percentile useful; Duration also excludes initialization.
• Keep Throttles separate from Errors, and investigate the source's retry behavior before changing concurrency.
• Give each notification an owner, a reason to respond, and a runbook or next diagnostic step.

There is no universal error-rate, duration, or memory threshold for every Lambda function. Calibrate alarms against real traffic, the service's acceptable failure rate, and the cost of a delayed or false page. See our guide to CloudWatch alarm thresholds, periods, and missing data for evaluation details.

Review logs, permissions, and alarm behavior

After a release or incident, check whether metrics and log fields still identify the intended function version and source. Review log retention against investigation and compliance needs, and use the shortest query range and fewest relevant log groups that answer the question. CloudWatch Logs retains data indefinitely unless a retention period is set, and ingestion, storage, and queries can incur charges.

Test missing-data behavior, notification delivery, and any automated action in a safe environment. When an alarm fires, inspect the alarm graph and history before changing a threshold: verify the namespace, dimensions, statistic, period, metric math expression, and datapoints that caused the state change.

Handle retries and responses safely

Trace cross-service failures with current instrumentation

A trace can show whether time was spent in the function or a downstream service, but use it alongside function metrics and request logs. X-Ray's service remains available; AWS recommends OpenTelemetry for new instrumentation because its X-Ray SDKs and daemon are in maintenance mode. Check AWS's X-Ray SDK migration guidance before adopting older setup instructions. Avoid assuming that a trace covers every invocation: sampling and instrumentation determine what is recorded.

Automate only bounded, retry-safe actions

CloudWatch alarm actions can notify an operator or invoke a Lambda function after a state change. A remediation function needs an explicit resource-based permission for the alarm and narrowly scoped permissions for the action it performs. Test duplicate delivery, repeated state changes, rollback behavior, and failure handling before relying on automation.

Do not automatically increase function memory or concurrency just because an error or latency alarm fired. First distinguish code errors, throttles, and downstream failures; then make a measured change with a clear rollback path. Lambda's Errors metric alone does not say which resource change will fix the incident.

Conclusion

A concise operating checklist

• Separate thrown function errors from handled application outcomes and throttles.
• Follow the trigger's delivery, retry, partial-batch, and failure-destination behavior.
• Combine Lambda metrics, source metrics, structured logs, and tracing only where each adds a useful signal.
• Set rate, count, latency, and missing-data alarm behavior from the workload and the response it requires.
• Make retries safe with idempotent processing and logs that identify a request or record without exposing sensitive payloads.

Current AWS references

The linked AWS documentation covers Lambda metrics, event-source retries, failure destinations, log formats, and CloudWatch alarm evaluation. Recheck the service references when changing runtime, event-source, or alarm configuration because those details can vary by trigger and feature.

FAQs

How can I get alerts for Lambda failures?

Create a CloudWatch alarm on the function's Errors metric for returned function and runtime errors. Add a separate alarm for Throttles when rejected requests matter, and use metric math for an error rate when traffic volume should affect the signal. Configure notifications or a safe alarm action, then test it. If you need alerts for handled business failures, emit a custom metric or structured log signal for those outcomes; the built-in Errors metric will not count a handler that returns normally.

What happens when Lambda encounters an error during event processing?

It depends on the invocation path:

• Synchronous invocation: Lambda returns the function response or error to the caller and does not automatically retry that function error. The caller or service decides whether to retry.
• Asynchronous invocation: after Lambda accepts the event into its queue, function errors are retried twice by default. Throttles and system errors are retried for up to the configured event age, which defaults to six hours. Configure retry and event-age limits, and use an on-failure destination or DLQ if failed events must be retained.
• Event source mapping: behavior belongs to the mapping and source. SQS messages can reappear after a visibility timeout and eventually move to a source-queue DLQ under its redrive policy. Kinesis and DynamoDB Streams retry batches according to mapping settings and stream retention; partial batch responses must be enabled before Lambda uses them.

Sources and clients can deliver duplicates, so make processing idempotent. For asynchronous invocation details, see AWS's guides to retry behavior and failure destinations and DLQs. For SQS, configure its source queue's redrive policy.