fix: stop reading private aws-cdk-lib Function.environment field

[ava-silver]

What does this PR do?

Removes all reads of aws-cdk-lib's private Function.environment field from the library. Every read is replaced with a WeakMap-backed tracker that records the library's own addEnvironment calls. Adds a public DatadogLambda.setEnvironment() method so users can seed env vars the construct will respect.

Motivation

Closes #620

aws-cdk-lib changed Function.environment's internal shape in a semver-minor (2.252 → 2.253), breaking cdk synth for all users of sourceCodeIntegration (#596). The v4.0.0 fix re-pointed the access at the new internal shape and raised the peer floor -- it kept the private coupling, so the library remained one CDK refactor away from breaking again.

Three call sites read across the private boundary:

• env.ts -- setGitEnvironmentVariables reads DD_TAGS to append git metadata
• env.ts -- applyEnvVariables checks each key before writing a default
• datadog-lambda.ts -- overrideGitMetadata reads DD_TAGS to rewrite git components

Changes

src/env-tracker.ts (new)

• Module-level WeakMap<LambdaFunction, Map<string, string>> (ddEnvTracker) and three helpers -- setTrackedEnv, getTrackedEnv, hasTrackedEnv -- that record every env write the library makes. Internal, not re-exported from index.ts.

src/env.ts

• All addEnvironment calls in setGitEnvironmentVariables, applyEnvVariables, and setDDEnvVariables go through setTrackedEnv.
• Private field reads replaced with WeakMap lookups.
• setGitEnvironmentVariables parameter type tightened from any[] to LambdaFunction[].

src/datadog-lambda.ts

• overrideGitMetadata reads DD_TAGS from getTrackedEnv instead of lambdaFunction.environment.map.get(DD_TAGS), removing the any cast. Tag rewriting extracted to an upsertTag helper.
• Adds public setEnvironment(lambdaFunction, key, value), which writes through setTrackedEnv so the construct treats the value as one it manages.

README.md

• Documents the env var ordering: configure DD_* vars via DatadogLambdaProps; call func.addEnvironment() after addLambdaFunctions() to override; or call setEnvironment() before to seed a value the construct will respect.

Behavior change

Previously the library read the private field to detect whether the user had already set a DD_* var on a function before addLambdaFunctions(), skipping its default if so -- and to append git metadata onto a user-set DD_TAGS. Without a public CDK read API (which does not exist), arbitrary pre-set env vars are no longer visible to the construct. The new contract:

• Configure via props (recommended): use DatadogLambdaProps fields (enableDatadogTracing, logLevel, tags, etc.)
• Seed a construct-respected value: call datadogLambda.setEnvironment(func, key, value) before addLambdaFunctions(). The construct will not override it, and when source code integration is enabled it appends git metadata (git.commit.sha, git.repository_url) onto a seeded DD_TAGS rather than overriding it. This preserves the prior per-function DD_TAGS + git-metadata workflow.
• Override after: call func.addEnvironment("DD_*", value) after addLambdaFunctions() -- CDK's last-write-wins semantics handle this naturally.
• Other vars set before addLambdaFunctions() (not via setEnvironment): will be overridden by the library's defaults.

Testing Guidelines

The existing suite covers the tracker migration; two tests were updated to reflect the behavior change (comments explain the new contract), and the overrideGitMetadata tests now assert via Template.fromStack() instead of reading the CDK private field. New tests cover setEnvironment: git metadata appending onto a seeded DD_TAGS, and the construct not overriding a seeded value.

Run locally with yarn test.

Types of Changes

• Bug fix
• New feature
• Breaking change

Check all that apply

• This PR's description is comprehensive
• This PR contains breaking changes that are documented in the description
• This PR introduces new APIs or parameters that are documented and unlikely to change in the foreseeable future
• This PR impacts documentation, and it has been updated (or a ticket has been logged)
• This PR's changes are covered by the automated tests

[ava-silver]

• fix: stop reading private aws-cdk-lib Function.environment field #621 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[janine-c]

Just some optional writing suggestions 🙂

[ahammond]

Can we please get this merged?

[ava-silver]

Can we please get this merged?

We'll try to prioritize it, my main concern is that this version of the fix has a behavior change which may break some usage patterns. I have another potential option up as a separate PR, and I'll weight the options with the team before merging either.

Sorry for the delay, and thanks for your patience on this! I just want to make sure we're being careful before potentially releasing a breaking change.

[ahammond]

Appreciate the caution, and I get that the behaviour change needs weighing. But ISTM this is being triaged as a minor cleanup. From the consumer side it is major.

The un-patched library reads a private aws-cdk-lib field, so every consumer of sourceCodeIntegration breaks whenever CDK reshapes that internal. #596 was triggered by a semver-minor (2.252 -> 2.253), and the v4.0.0 fix kept the private coupling, so the next break is a when, not an if. We're an engineering org with compliance and audit obligations: dependency upkeep is mandatory, automated, and continuous. A library that can break cdk synth fleet-wide on any CDK minor is a landmine sitting in that pipeline and has already cost me audit findings.

This PR has been open since June 23, and I want to be direct about the consequences. Next week I'll remove our usage of this library and with it Datadog observability support for lambdas. Future observability work will land in our in-house observability platform. I'd rather not deal with this right now, but Datadog's failure to address our ongoing exposure from this issue in a timely way is forcing my hand.

[ava-silver]

@ahammond I've chatted with the team, and we'll go through with the current implementation, which includes a breaking change around setting environment variables. I'll work on getting this merged and released in the next couple days so you can migrate to the safer version.

[ava-silver]

@ahammond we're working on some additional changes before we release the next version (with a major version bump). it should be out sometime next week.