AWS Lambda Insights: Metrics, Setup, Costs, and Limits

CloudWatch Lambda Insights adds system-level telemetry to standard AWS Lambda functions. The extension reports resource and initialization data to CloudWatch so you can investigate how a function uses its execution environment.

What Lambda Insights shows

Lambda Insights emits embedded-metric-format performance events to CloudWatch. It publishes selected values as time-series metrics and keeps additional per-invocation fields available in logs. These are runtime and resource signals, not your application's business metrics.

Separate Lambda service metrics from Insights metrics

Lambda publishes service metrics such as Invocations, Errors, Duration, and Throttles in the AWS/Lambda namespace. Insights uses the separate LambdaInsights namespace. See the AWS Lambda metrics guide for the service-level metrics and their use.

Use logs for per-invocation details

Insights performance events are written to /aws/lambda-insights. The function's application and platform logs normally use /aws/lambda/<function-name>. Query the Insights events for fields such as cold_start and shutdown_reason; use the function log group for application messages and exceptions.

Alarms and dashboards use metrics

You can graph or alarm on published Insights metrics in CloudWatch. The Lambda Insights dashboard provides multi-function and single-function views in the current Region; it displays telemetry only after the extension is enabled and the function has run.

Interpret the signal in context

A high memory or initialization value can point to work worth investigating, but it does not identify the cause by itself. Compare equivalent traffic periods and check application logs and downstream dependencies before changing code or configuration.

Tracing is a separate capability

To follow a request across services, configure AWS X-Ray active tracing or CloudWatch Application Signals separately. When X-Ray is enabled, the single-function view can link an invocation's trace ID to the X-Ray trace map. Application Signals is a separate application-performance feature that can collect application metrics and traces; seeing a function in Lambda Insights does not enable it.

Enable the extension

Check runtime, CPU architecture, Region, execution-role permissions, and network access before expecting telemetry.

Check runtime, architecture, and Region

AWS supports the Lambda Insights agent on Lambda runtimes that use Amazon Linux 2 or Amazon Linux 2023 and support Lambda extensions. For ZIP deployments, the layer must also match the function's architecture and be available in its Region. AWS maintains separate current version tables for x86-64 and ARM64. Check these tables when selecting or updating a layer; do not reuse a stale version or ARN.

Enable it in the Lambda console

Open the function in the Lambda console and choose Configuration > Monitoring and operations tools.
Edit the additional monitoring tools, enable CloudWatch Lambda Insights, and save.
Confirm the function's execution role has CloudWatchLambdaInsightsExecutionRolePolicy. The console can attach it when your permissions allow; otherwise, attach it to the role.
Invoke the function, then open CloudWatch Insights > Lambda Insights.

The policy lets the extension create and write to the /aws/lambda-insights log group. The function still needs its normal permissions for application and platform logs. If it runs in a private VPC subnet without internet egress, provide CloudWatch Logs connectivity, such as a VPC endpoint.

Use deployment code or a container image

For ZIP packages, add the current LambdaInsightsExtension layer ARN for the function's Region, architecture, and chosen release, then grant the execution-role policy. Follow AWS's current CLI, CloudFormation, SAM, or CDK setup instructions. A CLI configuration update replaces the function's layer list, so retain any layers the function already needs.

Container-image functions cannot attach a Lambda layer. Install the architecture-specific Insights agent in the image using AWS's container deployment instructions, rebuild and deploy the image, and grant the same execution-role policy. Use a compatible Amazon Linux runtime environment.

Metrics and log queries

Time-series metrics for standard Lambda functions

The table lists metrics in the LambdaInsights namespace. Names, units, and descriptions follow AWS's current metric reference.

Metric	What it measures	Unit
`cpu_total_time`	Sum of CPU user and system time	Milliseconds
`init_duration`	Time in the execution environment's initialization phase	Milliseconds
`memory_utilization`	Maximum measured memory as a share of allocated memory	Percent
`used_memory_max`	Measured memory used by the execution environment	Megabytes
`total_memory`	Memory allocated to the function	Megabytes
`rx_bytes` / `tx_bytes`	Bytes received / sent by the function	Bytes
`total_network`	Sum of received and sent bytes	Bytes
`tmp_free` / `tmp_used`	Available / used space in `/tmp`	Bytes

Other useful values are event fields, not all separate time-series metrics. For example, cold_start marks a cold-start invocation, while init_duration measures its initialization time. The event's duration is function-code processing time and excludes cold-start time; standard Lambda's Duration metric has the same exclusion, as AWS documents in its metric reference. Use these alongside end-to-end latency when diagnosing what a caller experienced.

Open the dashboard

In CloudWatch, choose Insights > Lambda Insights, then open the multi-function or single-function view. Use the first to compare enabled functions and the second to inspect one function's metrics and logs. If X-Ray is enabled, the single-function view may also link to a trace map.

Find cold-start invocations

In CloudWatch Logs Insights, select /aws/lambda-insights and query recent performance events. This example separates initialization duration from function-code duration:

filter event_type = "performance" and cold_start = true
| fields @timestamp, function_name, version, request_id,
         init_duration, duration, memory_utilization, used_memory_max
| sort @timestamp desc
| limit 100

For standard service metrics and ways to investigate them alongside logs, see how to analyze Lambda metrics in CloudWatch.

Use standard Lambda metrics for concurrency

Insights is not the source for standard concurrency metrics. Use ConcurrentExecutions, Throttles, and provisioned-concurrency metrics in the AWS/Lambda namespace. See AWS's concurrency metrics reference.

Do not treat event fields as a bill

An event may contain billed_duration, but that field is not a complete cost metric. It excludes other Lambda and CloudWatch charges; use billing tools for actual cost.

Understand Lambda Insights costs

Account for the extension, metrics, and logs

AWS charges for Lambda Insights extension execution time in 1-millisecond increments. Insights also sends performance events to CloudWatch Logs and publishes metrics, so include log ingestion and retention, metric storage, and Logs Insights queries in your estimate. Costs depend on invocation volume, event size, retention, query volume, Region, and current pricing; there is no single price that applies to every function.

Estimate for the workload

Use current CloudWatch pricing and Lambda pricing for the function's Region. Estimate from representative invocation volume and telemetry, include the log retention period and query volume, and compare that cost with the operational value of the data.

Limit avoidable log and query charges

Set log retention to match investigation and compliance needs.
Query the smallest practical time range and log group; Logs Insights charges can depend on data scanned.
Enable the extension for functions whose resource telemetry is useful, and review the resulting volume.
Manage the extension through the same deployment process as the function so the configuration stays reproducible.

Investigate performance and missing data

Start from the symptom

For high memory use, compare used_memory_max with allocated memory. For slow initialization, inspect init_duration and the cold_start field. For a slow invocation, separate initialization from function-code duration, then check the function logs and downstream services. Insights helps narrow the investigation; it does not tune memory, concurrency, code, or network settings.

Check for missing or late telemetry

If events are missing, revisit the runtime, layer or image, execution-role, and VPC checks in the setup section. AWS notes telemetry may be delayed by up to 20 minutes because data can remain buffered when an execution environment becomes idle. Check the function's log group for extension errors; set LAMBDA_INSIGHTS_LOG_LEVEL=info to troubleshoot when needed. See AWS's troubleshooting guide.

Validate any change

After changing code or configuration, compare the same kind of traffic, function version, errors, latency, and cost. Do not assume enabling Insights improves performance. For separate cold-start mitigation options, see the Lambda cold-start guide.