# LambdaInsightsExtension: setup and missing metrics fixes

> LambdaInsightsExtension is the AWS Lambda Insights layer name. Choose a verified regional ARN, grant collector log permissions, and diagnose missing metrics.

By Boris Tane, Founder of Polylane · Published October 6, 2026 · 6 min read
Canonical: https://polylane.com/learn/troubleshooting/LambdaInsightsExtension/

LambdaInsightsExtension is the official x86-64 layer name for CloudWatch Lambda Insights; ARM64 uses LambdaInsightsExtension-Arm64. Attach the ARN from AWS's current table for the function's Region and architecture, grant collector logging permissions, and verify performance logs and extracted metrics. It is not an error code or a metric name.

`LambdaInsightsExtension` is the official x86-64 layer name for CloudWatch Lambda Insights, not an exception or a metric. AWS's [x86-64 table](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-extension-versionsx86-64.html) uses that name, and its [ARM64 table](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-extension-versionsARM.html) uses `LambdaInsightsExtension-Arm64`. For missing data, verify the collector on the invoked version, its logging permissions, delivery path and EMF performance events.

The extension adds execution-environment evidence that ordinary invocation counters do not provide. It does not automatically instrument every application span or establish whether a business transaction succeeded.

## Meaning: system collector, layer name and namespace

The [Lambda Insights overview](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights.html) describes collection of CPU, memory, disk and network metrics, plus cold-start and worker-shutdown diagnostic information. For standard functions it emits a performance log event per invocation, with CloudWatch extracting metrics through embedded metric format.

The [standard-function definitions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-metrics-lambda-functions.html) distinguish `LambdaInsights` time series from additional fields in performance logs:

| Signal | Where to inspect | Meaning |
| --- | --- | --- |
| `cpu_total_time` | Metrics and logs | CPU time in milliseconds, not wall-clock duration |
| `init_duration` | Metrics | Time in the execution environment's init phase |
| `memory_utilization`, `used_memory_max` | Metrics and logs | Memory pressure and measured environment memory |
| `tmp_used`, `tmp_free` | Metrics | Temporary-storage use and free space |
| `rx_bytes`, `tx_bytes`, `total_network` | Metrics and logs | Network bytes, including runtime activity |
| `agent_version`, `agent_memory_max`, `fd_use` | Performance logs | Collector version, memory and descriptor evidence |

Not every log field is a standalone time series. Searching for `agent_version` in the metrics browser is not a reliable installation check. Native invocation metrics remain in the separate `AWS/Lambda` namespace.

For Lambda Managed Instances, use AWS's [separate metrics table](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-metrics-managed-instances.html). The extension version notes describe one-minute EMF emission for that environment. Do not apply standard per-invocation expectations to its collection path.

## Pick regional and architecture ARNs from current tables

An ARN includes Region, publisher account, layer name and a numeric layer version. The final number is not the software release number and can vary for the same release across Regions. Neither swapping a Region string nor guessing an increment gives a verified artifact.

The official tables, checked on 6 October 2026, provide these examples:

| Architecture and Region | Software release | Full ARN |
| --- | --- | --- |
| x86-64, `us-east-1` | `1.0.776.0` | `arn:aws:lambda:us-east-1:580247275435:layer:LambdaInsightsExtension:66` |
| x86-64, `us-east-2` | `1.0.776.0` | `arn:aws:lambda:us-east-2:580247275435:layer:LambdaInsightsExtension:71` |
| ARM64, `us-east-1` | `1.0.660.0` | `arn:aws:lambda:us-east-1:580247275435:layer:LambdaInsightsExtension-Arm64:31` |
| ARM64, `us-east-2` | `1.0.660.0` | `arn:aws:lambda:us-east-2:580247275435:layer:LambdaInsightsExtension-Arm64:33` |

These are dated examples from the [x86-64](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-extension-versionsx86-64.html) and [ARM64](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-extension-versionsARM.html) tables, not a permanent latest alias. Recheck the applicable table before installation. Availability and releases do not necessarily match across architectures.

The x86-64 `1.0.776.0` notes describe an RPM packaging fix. That can explain a collector that fails to start in an affected image, but it does not prove every telemetry gap has that cause. Correlate release notes with installed package versions and actual startup errors.

## Confirm the real function and invoked version

Inspect configuration before attaching anything:

```bash
export AWS_REGION=us-east-1
FUNCTION=orders-worker
aws lambda get-function-configuration --function-name "$FUNCTION" \
  --query '{Architecture:Architectures,Runtime:Runtime,Package:PackageType,Role:Role,Layers:Layers,VPC:VpcConfig,State:State}'
aws lambda get-alias --function-name "$FUNCTION" --name live
```

For alias traffic, inspect its resolved version too. Updating `$LATEST` does not change an existing published version. In the console check **Layers**, **Runtime settings**, **Configuration → Permissions**, and the selected version or alias.

The [overview](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights.html) supports agent runtimes based on Amazon Linux 2 and Amazon Linux 2023. For ZIP functions, attach the architecture-matched layer. For image functions, follow the [container setup procedure](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-Getting-Started-docker.html) to install the extension package in the image; attaching a ZIP layer is not equivalent.

## Install while preserving existing layers

AWS's [CLI setup](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-Getting-Started-cli.html) requires the collector's execution-role policy:

```bash
aws iam attach-role-policy --role-name orders-worker-role \
  --policy-arn arn:aws:iam::aws:policy/CloudWatchLambdaInsightsExecutionRolePolicy
```

This example is for the commercial partition. Use the role actually attached to the function. The [policy reference](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLambdaInsightsExecutionRolePolicy.html) grants log-group creation and stream/event writes for `/aws/lambda-insights`; the collector uses EMF extraction rather than requiring a handler `PutMetricData` call.

`--layers` replaces the whole layer list. Keep other layers and replace an existing Insights collector rather than adding a second one. This Boto3 example deliberately targets an x86-64 ZIP function in `us-east-1`; substitute a verified ARN for other targets:

```python
import boto3

client = boto3.client("lambda", region_name="us-east-1")
name = "orders-worker"
insights_arn = "arn:aws:lambda:us-east-1:580247275435:layer:LambdaInsightsExtension:66"
cfg = client.get_function_configuration(FunctionName=name)
assert cfg["PackageType"] == "Zip"
assert cfg["Architectures"] == ["x86_64"]
other_layers = [
    layer["Arn"] for layer in cfg.get("Layers", [])
    if layer["Arn"].split(":layer:")[1].split(":")[0]
    not in {"LambdaInsightsExtension", "LambdaInsightsExtension-Arm64"}
]
client.update_function_configuration(
    FunctionName=name, RevisionId=cfg["RevisionId"],
    Layers=other_layers + [insights_arn],
)
client.get_waiter("function_updated_v2").wait(FunctionName=name)
```

Check the five-layer and total unzipped package-size limits first. `RevisionId` avoids silently overwriting a concurrent configuration update. Put the equivalent change in infrastructure code for repeatability, then publish and route traffic according to your normal version workflow.

## Missing metrics: identify the first failed stage

Run a harmless test invocation through the target. Inspect **CloudWatch → Logs → Log groups → /aws/lambda-insights** in the same Region and account. Filter by function and read current timestamps and `agent_version`. A terminal starting point is:

```bash
aws logs tail /aws/lambda-insights --since 10m --format short
aws cloudwatch list-metrics --namespace LambdaInsights \
  --dimensions Name=function_name,Value=orders-worker
```

The dimension is `function_name`, optionally accompanied by `version`; it is not native Lambda's `FunctionName`. Incorrect dimensions can produce an empty chart even when data exists.

In Logs Insights, select `/aws/lambda-insights` and run a function-scoped query over the test's time window:

```text
fields @timestamp, function_name, version, agent_version, cpu_total_time, used_memory_max
| filter function_name = "orders-worker"
| sort @timestamp desc
| limit 20
```

Compare the version in these events with the version resolved by the alias. If only an older version appears, confirm which version received the test traffic before changing collector permissions. Save one representative performance event and its timestamp as installation evidence, then query the matching metric interval rather than an arbitrary current chart window.

**No performance logs:** confirm the invoked version contains the collector, its architecture matches, and startup logs show no extension failure. Check execution-role log permissions. For private subnets without internet access, the CLI setup requires a CloudWatch Logs interface VPC endpoint if one is absent. Inspect endpoint policy, private DNS and security-group connectivity; IAM cannot fix a blocked delivery route.

**Logs exist but no extracted metric:** inspect EMF metadata and the metric's namespace, dimensions and timestamp. Choose a field actually listed as aggregated, use an invocation-covering time range and allow ingestion time. The [AWS_EMF_ENVIRONMENT guide](/learn/troubleshooting/AWS_EMF_ENVIRONMENT/) explains the extraction contract, but that application-library variable is not a documented collector configuration switch.

**Native metrics exist but Insights does not:** they have independent production paths. `Invocations` does not establish layer installation or performance-log delivery. For a request rejected during [EC2ThrottledException initialization](/learn/troubleshooting/EC2ThrottledException/), use caller and state evidence rather than expecting a collector sample for every rejected invocation.

## Cost, cold starts and verification

AWS's [pricing section](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights.html) charges for metrics/logs and consumed extension execution time in one-millisecond increments. Consult current CloudWatch and Lambda prices for the Region; there is no universal cost per installed layer.

Extensions [share CPU, memory and storage](https://docs.aws.amazon.com/lambda/latest/dg/using-extensions.html) and must complete initialization before code runs. Compare equivalent enabled and disabled versions under the same workload. Inspect cold-start latency, `init_duration`, memory, billed duration and `PostRuntimeExtensionsDuration`. The last measures extension work after the runtime, not all initialization overhead.

Verify current performance logs, expected time-series datapoints, a successful business result and acceptable resource/latency impact. Pin the ARN in infrastructure code, review release notes before upgrades and repeat after runtime, architecture, role or VPC changes. Define a separate [read-access identity](/learn/ai-in-production/is-it-safe-to-give-an-ai-sre-read-access-to-production/) for investigations.

Polylane connects to [AWS](/integrations/aws/), so it can see when a function breaks there and work out why. The collector still needs to be installed and delivering data; its layer name alone cannot reveal missing CPU or memory samples.

Running on AWS? See [how Polylane monitors AWS in production](https://polylane.com/for/aws/).

## Common questions

**Is LambdaInsightsExtension an error?**

No. It is the official x86-64 layer name in AWS's published ARNs. ARM64 uses LambdaInsightsExtension-Arm64. The metrics namespace is LambdaInsights, not the layer name.

**Can one layer ARN work in every Region?**

No. Copy the full ARN from the current AWS table for the function's Region and architecture. Publisher IDs and layer version numbers vary; software release numbers are not numeric layer versions.

**Does the collector require cloudwatch:PutMetricData?**

Its documented execution-role policy grants CloudWatch Logs operations. The extension writes EMF performance events and CloudWatch extracts metrics from those logs.

**Is Lambda Insights free or overhead-free?**

No. Logs, metrics and consumed extension execution time are billed. Extensions share CPU, memory and storage and must initialize before invocation, so compare enabled and disabled versions under an equivalent workload.

**Why do native metrics appear while Insights is empty?**

They use separate paths. Native metrics do not prove the invoked version has the collector installed or that performance logs arrived. Check the layer, execution role, networking and /aws/lambda-insights log group.

## Sources

- [Lambda Insights overview](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights.html)
- [Official x86-64 versions and ARNs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-extension-versionsx86-64.html)
- [Official ARM64 versions and ARNs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-extension-versionsARM.html)
- [Lambda Insights CLI setup](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-Getting-Started-cli.html)
- [Collector execution-role policy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLambdaInsightsExecutionRolePolicy.html)
- [Standard-function metric definitions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-metrics-lambda-functions.html)
- [Extension lifecycle and resource impact](https://docs.aws.amazon.com/lambda/latest/dg/using-extensions.html)
- [Container-image installation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-Getting-Started-docker.html)
- [Polylane AWS integration](https://docs.polylane.com/integrations/aws)

## About the author

Boris Tane is the founder of Polylane. He previously founded Baselime, observability for the future of the cloud, which Cloudflare acquired. At Cloudflare he built and led the Workers observability team.

## Related

- [AWS_EMF_ENVIRONMENT: valid values and missing EMF fixes](https://polylane.com/learn/troubleshooting/AWS_EMF_ENVIRONMENT/): AWS_EMF_ENVIRONMENT overrides EMF library detection. Check Node, Python and Java values separately, trace stdout or agent delivery, and fix missing metrics.
- [EC2ThrottledException: fix Lambda EC2 API throttling](https://polylane.com/learn/troubleshooting/EC2ThrottledException/): EC2ThrottledException means EC2 throttled Lambda initialization. Check VPC state and API activity, distinguish concurrency limits, and verify a safe recovery.
- [Is It Safe to Give an AI SRE Read Access to Production?](https://polylane.com/learn/ai-in-production/is-it-safe-to-give-an-ai-sre-read-access-to-production/): Read access for an AI SRE is a sound first step if you scope it. The risks are secrets, customer data and exfiltration. Here are the controls and a checklist.
- [Fix 403 Forbidden (Access Denied) from Amazon S3](https://polylane.com/learn/troubleshooting/aws-403-forbidden/): Why Amazon S3 returns 403 Forbidden: Block Public Access, missing s3:ListBucket, object ownership, clock skew, expired presigned URLs and CloudFront. Fix each.
- [Fix 502 Bad Gateway on AWS API Gateway and Load Balancers](https://polylane.com/learn/troubleshooting/aws-502-bad-gateway/): Why AWS returns 502 Bad Gateway from API Gateway or an Application Load Balancer, how to find which hop wrote it, and the fix for each cause.

Get started with one command: `curl -fsSL https://polylane.com/setup | bash` installs the CLI, connects your coding agents, and creates the account.