feat(aws-cdk-lib): emits performance counters if synthesis is slow (#37919)

(This is a re-roll of #37843, to account for the warning emitted by `fs-extra` if it detects monkey patching)

If the framework determines that synthesis is taking a long time (more than 10 seconds per stack, which is extremely unlikely high; we may adjust this threshold over time) it will emit a file with performance counters to the file indicated by the `$CDK_PERF_COUNTERS_FILE` environment variable.

The CLI is responsible for sending this report in as telemetry, or not if disabled.

The reporting can be disabled altogether by passing a property to `App`, or setting a context key in `cdk.json`:

```ts
new App({
  performanceReporting: false,
});
```

```js
{
  "context": {
    "aws:cdk:performance-reporting": false,
  },
}
```

Performance profiling works by making functions emit `measure` events to the Node [performance measurement APIs](https://nodejs.org/api/perf_hooks.html). The new `perf.ts` file provides a number of helper functions to decorate classes and functions to make them emit measurement information. A number of CDK APIs that we suspect of being slow are annotated by default, and some global NodeJS APIs that are typical sources of slowness (filesystem access, subprocess spawns) are annotated as well.

CDK users are free to use these functions as well and the `printPerfCounters()` function to do their own profiling.

At the end of synthesis, only those counters annotated with `{ telemetry: true }` are written to the telemetry file and sent to the server.

Here is an example of a set of perf counters (extracted from a test):

```js
{
  'phase:Construction': 12154,
  'phase:Construction(cnt)': 1,
  'bundle:NodejsFunction': 12133,
  'bundle:NodejsFunction(cnt)': 2,
  'DockerImage.fromBuild': 10957,
  'DockerImage.fromBuild(cnt)': 1,
  'phase:Load': 3940,
  'phase:Load(cnt)': 1,
  'AssetBundlingBindMount.run': 1176,
  'AssetBundlingBindMount.run(cnt)': 1,
  'phase:Synthesis': 26,
  'phase:Synthesis(cnt)': 1,
  'Stack.resolve': 7,
  'Stack.resolve(cnt)': 47,
  'FileSystem.fingerprint': 1,
  'FileSystem.fingerprint(cnt)': 1,
  'FileSystem.isEmpty': 0,
  'FileSystem.isEmpty(cnt)': 1
}
```

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

### Issue # (if applicable)

Closes #<issue number here>.

### Reason for this change



### Description of changes



### Describe any new or updated permissions being added




### Description of how you validated changes



### Checklist
- [ ] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: rix0rrr

packages/@aws-cdk/aws-lambda-go-alpha/lib/bundling.ts

@@ -3,6 +3,7 @@ import * as path from 'path';
 import type { Architecture, AssetCode } from 'aws-cdk-lib/aws-lambda';
 import { Code, Runtime } from 'aws-cdk-lib/aws-lambda';
 import * as cdk from 'aws-cdk-lib/core';
+import { profileSpan } from 'aws-cdk-lib/core/lib/helpers-internal';
 import type { BundlingOptions } from './types';
 import { exec, findUp, getGoBuildVersion } from './util';
 
@@ -102,6 +103,8 @@ export class Bundling implements cdk.BundlingOptions {
 
   private static runsLocally?: boolean;
 
+  public readonly [cdk.PERF_BUNDLING_SRC_SYM] = 'GoFunction';
+
   // Core bundling options
   public readonly image: cdk.DockerImage;
   public readonly command: string[];
@@ -142,16 +145,28 @@ export class Bundling implements cdk.BundlingOptions {
 
     // Docker bundling
     const shouldBuildImage = props.forcedDockerBundling || !Bundling.runsLocally;
-    this.image = shouldBuildImage
-      ? props.dockerImage ?? cdk.DockerImage.fromBuild(path.join(__dirname, '..', 'lib'), {
+
+    if (shouldBuildImage && props.dockerImage) {
+      // Use the user's image
+      this.image = props.dockerImage;
+    } else if (shouldBuildImage && !props.dockerImage) {
+      // Build our own image to run esbuild in. We do some counter trickery here: we do want to count
+      // the time spent here as part of 'bundle:GoFunction', but by default only the RUNNING of the Docker
+      // image would count as that. So we add an additional timer span just for the building of the runner image.
+      using _span = profileSpan(`bundle:${this[cdk.PERF_BUNDLING_SRC_SYM]}`, { telemetry: true, skipCount: true });
+
+      this.image = cdk.DockerImage.fromBuild(path.join(__dirname, '..', 'lib'), {
         buildArgs: {
           ...props.buildArgs ?? {},
           IMAGE: Runtime.GO_1_X.bundlingImage.image, // always use the GO_1_X build image
         },
         platform: props.architecture.dockerPlatform,
         network: props.network,
-      })
-      : cdk.DockerImage.fromRegistry('dummy'); // Do not build if we don't need to
+      });
+    } else {
+      // We won't use a Docker image, but this field must have a value.
+      this.image = cdk.DockerImage.fromRegistry('dummy');
+    }
 
     const bundlingCommand = this.createBundlingCommand(cdk.AssetStaging.BUNDLING_INPUT_DIR, cdk.AssetStaging.BUNDLING_OUTPUT_DIR);
     this.command = props.command ?? ['bash', '-c', bundlingCommand];
@@ -177,6 +192,8 @@ export class Bundling implements cdk.BundlingOptions {
             return false;
           }
 
+          using _span = profileSpan('GoFunction#tryBundle', { telemetry: true });
+
           const localCommand = createLocalCommand(outputDir);
           exec(
             osPlatform === 'win32' ? 'cmd' : 'bash',

packages/@aws-cdk/aws-lambda-python-alpha/lib/bundling.ts

@@ -2,7 +2,8 @@ import * as path from 'path';
 import type { AssetCode, Runtime } from 'aws-cdk-lib/aws-lambda';
 import { Architecture, Code } from 'aws-cdk-lib/aws-lambda';
 import type { BundlingFileAccess, BundlingOptions as CdkBundlingOptions, DockerVolume } from 'aws-cdk-lib/core';
-import { AssetStaging, DockerImage } from 'aws-cdk-lib/core';
+import { AssetStaging, DockerImage, PERF_BUNDLING_SRC_SYM } from 'aws-cdk-lib/core';
+import { profileSpan } from 'aws-cdk-lib/core/lib/helpers-internal';
 import { Packaging, DependenciesFile } from './packaging';
 import type { BundlingOptions, ICommandHooks } from './types';
 
@@ -64,6 +65,7 @@ export class Bundling implements CdkBundlingOptions {
     });
   }
 
+  public readonly [PERF_BUNDLING_SRC_SYM] = 'PythonFunction';
   public readonly image: DockerImage;
   public readonly entrypoint?: string[];
   public readonly command: string[];
@@ -101,14 +103,24 @@ export class Bundling implements CdkBundlingOptions {
       assetExcludes,
     });
 
-    this.image = image ?? DockerImage.fromBuild(path.join(__dirname, '..', 'lib'), {
-      buildArgs: {
-        ...props.buildArgs,
-        IMAGE: runtime.bundlingImage.image,
-      },
-      platform: architecture.dockerPlatform,
-      network: props.network,
-    });
+    if (image) {
+      // Use the user's image
+      this.image = image;
+    } else {
+      // Build our own image to do the build in in. We do some counter trickery here: we do want to count
+      // the time spent here as part of 'bundle:PythonFunction', but by default only the RUNNING of the Docker
+      // image would count as that. So we add an additional timer span just for the building of the runner image.
+      using _span = profileSpan(`bundle:${this[PERF_BUNDLING_SRC_SYM]}`, { telemetry: true, skipCount: true });
+      this.image = DockerImage.fromBuild(path.join(__dirname, '..', 'lib'), {
+        buildArgs: {
+          ...props.buildArgs,
+          IMAGE: runtime.bundlingImage.image,
+        },
+        platform: architecture.dockerPlatform,
+        network: props.network,
+      });
+    }
+
     this.command = props.command ?? ['bash', '-c', chain(bundlingCommands)];
     this.entrypoint = props.entrypoint;
     this.volumes = props.volumes;

packages/aws-cdk-lib/aws-lambda-nodejs/lib/bundling.ts

@@ -12,6 +12,7 @@ import { Code, Runtime } from '../../aws-lambda';
 import * as cdk from '../../core';
 import { AssumptionError, ValidationError } from '../../core';
 import { lit } from '../../core/lib/private/literal-string';
+import { profileFn, profileSpan } from '../../core/lib/private/perf';
 import { LAMBDA_NODEJS_SDK_V3_EXCLUDE_SMITHY_PACKAGES } from '../../cx-api';
 
 const ESBUILD_MAJOR_VERSION = '0';
@@ -84,6 +85,8 @@ export class Bundling implements cdk.BundlingOptions {
   private static esbuildInstallation?: PackageInstallation;
   private static tscInstallation?: PackageInstallation;
 
+  public readonly [cdk.PERF_BUNDLING_SRC_SYM] = 'NodejsFunction';
+
   // Core bundling options
   public readonly image: cdk.DockerImage;
   public readonly entrypoint?: string[];
@@ -183,8 +186,17 @@ export class Bundling implements cdk.BundlingOptions {
 
     // Docker bundling
     const shouldBuildImage = props.forceDockerBundling || !Bundling.esbuildInstallation;
-    this.image = shouldBuildImage ? props.dockerImage ?? cdk.DockerImage.fromBuild(path.join(__dirname, '..', 'lib'),
-      {
+
+    if (shouldBuildImage && props.dockerImage) {
+      // Use the user's image
+      this.image = props.dockerImage;
+    } else if (shouldBuildImage && !props.dockerImage) {
+      // Build our own image to run esbuild in. We do some counter trickery here: we do want to count
+      // the time spent here as part of 'bundle:NodejsFunction', but by default only the RUNNING of the Docker
+      // image would count as that. So we add an additional timer span just for the building of the runner image.
+      using _span = profileSpan(`bundle:${this[cdk.PERF_BUNDLING_SRC_SYM]}`, { telemetry: true, skipCount: true });
+
+      this.image = cdk.DockerImage.fromBuild(path.join(__dirname, '..', 'lib'), {
         buildArgs: {
           ...props.buildArgs ?? {},
           // If runtime isn't passed use regional default, lowest common denominator is node18
@@ -193,8 +205,11 @@ export class Bundling implements cdk.BundlingOptions {
         },
         platform: props.architecture.dockerPlatform,
         network: props.network,
-      })
-      : cdk.DockerImage.fromRegistry('dummy'); // Do not build if we don't need to
+      });
+    } else {
+      // We won't use a Docker image, but this field must have a value.
+      this.image = cdk.DockerImage.fromRegistry('dummy');
+    }
 
     const bundlingCommand = this.createBundlingCommand(scope, {
       inputDir: cdk.AssetStaging.BUNDLING_INPUT_DIR,
@@ -455,6 +470,7 @@ export class Bundling implements cdk.BundlingOptions {
     return steps;
   }
 
+  @profileFn('NodejsFunction#tryBundle', { telemetry: true })
   private executeBundlingSteps(scope: IConstruct, steps: BundlingStep[]) {
     const cwd = this.projectRoot;
     const osPlatform = os.platform();

packages/aws-cdk-lib/aws-lambda-nodejs/test/e2e/bundling-e2e.test.ts

@@ -4,7 +4,9 @@ import * as child_process from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { performance } from 'perf_hooks';
 import type { SerializableNodejsFunctionProps } from './types';
+import { cx_api } from '../../..';
 import { OutputFormat } from '../../lib';
 
 // Paths resolved once
@@ -73,6 +75,10 @@ const LOCK_FILES: Record<PackageManager, { name: string; content: string }> = {
 jest.setTimeout(3_000_000);
 
 let project: TestProject;
+
+beforeEach(() => {
+  performance.clearMeasures();
+});
 afterEach(() => project?.cleanup());
 
 describeDockerSuite((forceDockerBundling) => {
@@ -250,14 +256,64 @@ describeDockerSuite((forceDockerBundling) => {
             afterBundling: [],
             beforeBundling: [],
             beforeInstall: ['echo INSTALL > {outputDir}/install-marker.txt'],
-
           },
         },
       });
 
       const files = assetFiles(project.outdir);
       expect(files).toContain('install-marker.txt');
     });
+
+    test('performance counters are emitted', () => {
+      project = createProject(pkgManager, '.ts');
+
+      const countersFile = path.join(project.outdir, 'counters.json');
+      process.env[cx_api.PERF_COUNTERS_FILE_ENV] = countersFile;
+      try {
+        cdkSynth(project, {
+          entry: project.entryFile,
+          bundling: {
+            forceDockerBundling,
+            commandHooks: {
+              beforeBundling: ['echo "export function init() { }" > {inputDir}/module.ts'],
+              beforeInstall: [],
+              afterBundling: [],
+            },
+          },
+          context: {
+            // If we don't set this, direct esbuild invocations are too fast to get emitted
+            '@aws-cdk/core.slowSynthThreshold': '0',
+          },
+        });
+
+        // If beforeBundling failed, cdk synth would have failed (commands are chained with &&)
+        const counters = JSON.parse(fs.readFileSync(countersFile, 'utf-8')).counters;
+
+        if (forceDockerBundling) {
+          // Docker bundling has 2 counters: build the docker image, then run the docker image.
+          // A single counter should encompass both of them.
+          expect(counters).toMatchObject({
+            'bundle:NodejsFunction': expect.anything(),
+            'bundle:NodejsFunction(cnt)': 1,
+            'DockerImage.fromBuild': expect.anything(),
+            'AssetBundlingBindMount.run': expect.anything(),
+          });
+
+          expect(counters['bundle:NodejsFunction']).toBeGreaterThanOrEqual(counters['DockerImage.fromBuild'] + counters['AssetBundlingBindMount.run']);
+        } else {
+          // Local bundling has 1 counter: do the bundling
+          expect(counters).toMatchObject({
+            'bundle:NodejsFunction': expect.anything(),
+            'bundle:NodejsFunction(cnt)': 1,
+            'NodejsFunction#tryBundle': expect.anything(),
+          });
+
+          expect(counters['bundle:NodejsFunction']).toBeGreaterThanOrEqual(counters['NodejsFunction#tryBundle']);
+        }
+      } finally {
+        delete process.env[cx_api.PERF_COUNTERS_FILE_ENV];
+      }
+    });
   });
 });
 
@@ -513,6 +569,7 @@ function cdkSynth(proj: TestProject, config: SerializableNodejsFunctionProps): {
       '--no-path-metadata',
       '--no-asset-metadata',
       '--quiet',
+      ...Object.entries(config.context ?? {}).flatMap(([key, value]) => ['--context', `${key}=${value}`]),
     ],
     {
       cwd: proj.dir,

packages/aws-cdk-lib/aws-lambda-nodejs/test/e2e/types.ts

@@ -8,6 +8,7 @@ export type SerializableNodejsFunctionProps = Omit<NodejsFunctionProps, 'runtime
     forceDockerBundling: boolean;
     commandHooks?: {[K in keyof ICommandHooks]: ReturnType<ICommandHooks[K]> };
   };
+  context?: Record<string, string>;
 };
 
 export type RuntimeKey = 'NODEJS_LATEST' | 'NODEJS_20_X' | 'NODEJS_22_X' | 'NODEJS_24_X';