Add the Ivy Lambda layer by hand (CDK, SAM, Serverless, Terraform)

What to add

Setting	Value
Layer	`ivy-trace-nodejs` (see "Getting the layer" below)
`AWS_LAMBDA_EXEC_WRAPPER`	`/opt/ivy-wrapper`
`IVY_ENDPOINT`	Your ingest endpoint. Spans go to `<endpoint>/v1/traces`
`IVY_API_KEY`	A project ingest key. It decides which workspace and project the traces belong to

No code changes. Without IVY_ENDPOINT the wrapper leaves your handler alone.

Getting the layer. When you connect an AWS account, Ivy publishes ivy-trace-nodejs in your account and region. Copy the exact layer version ARN from a function Ivy traces (its configuration lists the layer), or from the dashboard. Self-hosting without a connected account? Build the layer from source and publish it yourself: see the layer README.

Getting the endpoint and key. The ingest endpoint is shown in Workspace settings → AWS accounts (and in GET /api/w/<workspace>/aws/setup as ingest_endpoint). Create an ingest key per project in Settings → Projects, or with POST /api/w/<workspace>/p/<project>/keys. The key is shown once; store it like your other secrets.

Examples

AWS CLI (--environment replaces all variables, so include the function's existing ones):

aws lambda update-function-configuration \
  --function-name checkout-createOrder \
  --layers arn:aws:lambda:eu-west-1:123456789012:layer:ivy-trace-nodejs:1 \
  --environment 'Variables={AWS_LAMBDA_EXEC_WRAPPER=/opt/ivy-wrapper,IVY_ENDPOINT=https://<ingest endpoint>,IVY_API_KEY=<key>}'

AWS CDK:

const ivyLayer = lambda.LayerVersion.fromLayerVersionArn(this, "Ivy", ivyLayerArn);

new NodejsFunction(this, "CreateOrder", {
  entry: "src/create-order.ts",
  layers: [ivyLayer],
  environment: {
    AWS_LAMBDA_EXEC_WRAPPER: "/opt/ivy-wrapper",
    IVY_ENDPOINT: ivyEndpoint,
    IVY_API_KEY: ivyApiKey, // from Secrets Manager or SSM, not plain code
  },
});

Serverless Framework:

provider:
  layers:
    - arn:aws:lambda:eu-west-1:123456789012:layer:ivy-trace-nodejs:1
  environment:
    AWS_LAMBDA_EXEC_WRAPPER: /opt/ivy-wrapper
    IVY_ENDPOINT: ${param:ivyEndpoint}
    IVY_API_KEY: ${ssm:/ivy/api-key}

If auto-trace also covers these functions, set the tag ivy:trace=false on them, or leave them out of your rules, so Ivy doesn't change them behind your deploys.

Environment variables

Variable	Default
`AWS_LAMBDA_EXEC_WRAPPER`		`/opt/ivy-wrapper` turns tracing on
`IVY_ENDPOINT`		Ingest base URL
`IVY_API_KEY`		Sent as `Authorization: Bearer <key>`
`IVY_DISABLE`	`false`	Turn tracing off without removing the layer
`IVY_MAX_PAYLOAD_BYTES`	`16384`	Cap for each payload (event, response, bodies)
`IVY_REDACT_KEYS`	see span conventions	Comma-separated; a key is redacted if it contains one of these (case-insensitive, `-` and `_` ignored)
`IVY_CAPTURE_LOGS`	`true`	Record `console.*` calls on the trace
`IVY_CAPTURE_OTEL`	`true`	Capture spans that libraries create through `@opentelemetry/api` (Vercel AI SDK, …)
`IVY_PLATFORM_TELEMETRY`	`true`	Use the Lambda Telemetry API to report init errors, crashes, out of memory and timeouts
`IVY_REPORT_METRICS`	`true`	Send billed duration and max memory used
`IVY_TIMEOUT_MARGIN_MS`	`100`	How long before the deadline to snapshot spans for a possible timeout
`IVY_EXPORT_TIMEOUT_MS`	`1000`	Per-request export timeout
`IVY_FLUSH_BUDGET_MS`	`2000`	Most time the extension spends exporting after each invocation
`IVY_MAX_QUEUE_SPANS`	`2000`	Spans buffered while the endpoint is unreachable
`IVY_DEBUG`	`false`	Log layer diagnostics

Requirements

Node.js runtime: nodejs22.x is tested, nodejs20.x should work (Node 20.16 or later).
x86_64 or arm64; one layer zip serves both.
Your function must be able to reach the ingest endpoint (outbound HTTPS, or a route to your self-hosted Ivy).
Not traced yet: response streaming handlers and Lambda multi-concurrency.

Manual layer setup

What to add

Examples

Environment variables

Requirements

Trace your first function today