# Lambda auto-instrumentation

Ivy instruments Node.js Lambda functions with one Lambda layer and no code changes. Connect an AWS account through a CloudFormation stack, choose which functions to trace by stack, name pattern or tag, and Ivy attaches the layer for you, including to new functions that match later.

## How the layer works

The layer has three small parts:

1. **An exec wrapper** (`AWS_LAMBDA_EXEC_WRAPPER=/opt/ivy-wrapper`) that loads Ivy's tracer before your handler. Without `IVY_ENDPOINT` it changes nothing.
2. **An in-process tracer** (32 KB) that records the invocation and patches the AWS SDK v3, `fetch` and `node:http`. It works with ESM and CommonJS handlers and with bundled code.
3. **A Lambda extension written in Rust** that exports the spans after your function has responded, and reads the Lambda Telemetry API to catch [failures outside the handler](https://ivytrace.dev/features/lambda-errors).

One layer zip serves both x86_64 and arm64.

## Opt-in auto-trace

Connecting an AWS account traces nothing by itself. You decide what to trace:

1. **Connect.** Ivy gives you a CloudFormation quick-create link. The stack creates an IAM role that Ivy assumes with an external ID, and an EventBridge rule that reports function changes. No access keys change hands.
2. **Pick.** Ivy lists your functions grouped by **CloudFormation stack**. Trace a whole stack, a name pattern (`checkout-*`) or a tag (`team=core`), optionally limited to an account and region. Each choice is saved as a rule that also names the [project](https://ivytrace.dev/docs/agent-setup) the traces go to. A dry run shows what a rule would select first.
3. **Stay in sync.** New functions that match a rule are traced automatically. Remove a rule, or exclude a function, and the next sync removes the layer and Ivy's environment variables again.

Function tags override rules: `ivy:trace=true` or `ivy:trace=false`, and `ivy:project=<slug>`.

## If you deploy with infrastructure as code

If CDK, SST, the Serverless Framework, SAM, Terraform or Pulumi manages your functions' layers and environment, the next deploy can remove what Ivy attached. In that case, add the layer and four environment variables to your infrastructure code instead. The [manual setup](https://ivytrace.dev/docs/manual-setup) page lists them, and the [agent setup](https://ivytrace.dev/docs/agent-setup) offers to do it for you.

## Performance

Your callers don't wait for Ivy: spans are sent by the extension after your function has responded. Measured on AWS Lambda (eu-west-1, Node.js 22, arm64 and x86_64, 128 MB and 1024 MB) in November 2026:

| Measure | Result |
|---|---|
| Warm response latency | No measurable difference at 1024 MB; about 1 ms at the median at 128 MB |
| Cold start (init duration) | About 20–45 ms at the median |
| Billed duration | About 15–20 ms per invocation at 1024 MB, for the export after the response |

The tracer is 32 KB, and the extension is written in Rust because a Node.js extension added about 30 ms to every cold start.

## Limits

- Node.js only, for now. A Python layer is next.
- Response streaming handlers and Lambda multi-concurrency are not traced.
- `undici` used directly is not traced (Node's global `fetch` is).

---

Source: https://ivytrace.dev/features/auto-instrumentation · Updated 2026-11-14