LambdaInsightsExtension: setup and missing metrics fixes

LambdaInsightsExtension is the official x86-64 layer name for CloudWatch Lambda Insights, not an exception or a metric. AWS’s x86-64 table uses that name, and its ARM64 table 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 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 distinguish LambdaInsights time series from additional fields in performance logs:

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. 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:

These are dated examples from the x86-64 and ARM64 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:

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 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 to install the extension package in the image; attaching a ZIP layer is not equivalent.

Install while preserving existing layers

AWS’s CLI setup requires the collector’s execution-role policy:

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 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:

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:

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:

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 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, use caller and state evidence rather than expecting a collector sample for every rejected invocation.

Cost, cold starts and verification

AWS’s pricing section 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 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 for investigations.

Polylane connects to 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.