Skip to main content
The Odigos AWS CDK package adds OpenTelemetry instrumentation to your AWS workloads from inside your own AWS CDK application — so instrumentation ships through the same pipeline as the rest of your infrastructure, reviewed in a pull request and applied by cdk deploy.
New to this? AWS CDK is a tool for describing cloud infrastructure in a programming language instead of a YAML template. If your team doesn’t use CDK, you don’t need this section — use the CloudFormation instructions on Instrument Lambda or Instrument Fargate, or let Odigos apply instrumentation for you.

​
When you’d use this

Odigos can instrument your workloads two ways, and the CDK package is for the second one: Pick self-managed when your infrastructure code should stay the single source of truth for what’s deployed. Pick Odigos-managed when you’d rather not touch your infrastructure code at all. Full comparison: Odigos-managed vs. self-managed instrumentation.
Don’t do both to the same workload. If a function or service is instrumented by your CDK app and also enabled as an Odigos-managed source, each side keeps reasserting its own configuration — every deploy fights every reconcile, and each round trip creates a new Lambda version or ECS task revision. Pick one per workload.

​
Install

TypeScript and JavaScript only, for now. A Python distribution (odigos-aws-cdk) is built but not yet published — it’s waiting on package-index approval. Until it’s out, Python CDK apps should use the CloudFormation instructions instead.
Pin an exact version. The package version is the instrumentation version — @odigos/aws-cdk@0.0.15 installs the OpenTelemetry layer and agents bundle built by Odigos release v0.0.15, and nothing resolves or moves at deploy time. Upgrading is a deliberate npm update followed by a cdk diff that shows you exactly what changes. An instrumentation agent that silently updated itself under a deployment that changed nothing is not a property you want.

​
The two constructs

Lambda construct

Every option for instrumenting Lambda functions.

Fargate construct

Every option for instrumenting ECS Fargate services.
Configure where telemetry goes and which signals to enable on CDK: Destinations — both constructs share the same destination options.

​
How Odigos recognizes your workload

Both constructs write an environment variable called ODIGOS_IAC onto everything they instrument. This is the one thing that tells Odigos “this workload is instrumented, and here’s what with.”
Without that marker, Odigos reports the workload as awaiting your deployment — no matter how completely everything else was applied. The constructs write it for you, so there’s nothing to switch on; it matters mainly because you’ll see it in a cdk diff, and because hand-written instrumentation has to include it too.
The marker also records which version of instrumentation you deployed — the layer ARN on Lambda, the agents image on Fargate. That’s what lets you pin a version and have Odigos respect it, rather than reporting your deliberately-pinned workload as out of date the day Odigos publishes something newer.
There’s a second marker, ODIGOS_MANAGED, that these constructs never write — and neither should you. That one is Odigos’ own record of a change it made, including the snapshot it would undo that change with. Writing it by hand claims a rollback point that doesn’t exist.

​
Turning on debug logging

​
boolean
default:"false"
Makes the OpenTelemetry agent log verbosely, which helps when telemetry isn’t arriving and you need to see why. Available on both constructs.
Leave it off once you’re done. It’s expensive at volume, and Odigos expects it off unless debug telemetry is also enabled on the connector — so leaving it on can itself be reported as drift.

​
Next steps

Destinations

Endpoint formats, credentials, and which signals to enable.

Lambda construct

Layer sources, web-server mode, Java handler interfaces.

Fargate construct

Languages, service naming, the agents image.