feat(cli): send telemetry events to local file

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/synth/cdk-synth-telemetry-with-errors.integtest.ts

@@ -0,0 +1,127 @@
+import * as path from 'path';
+import * as fs from 'fs-extra';
+import { integTest, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'cdk synth with telemetry and validation error leads to invoke failure',
+  withDefaultFixture(async (fixture) => {
+    const telemetryFile = path.join(fixture.integTestDir, `telemetry-${Date.now()}.json`);
+    const output = await fixture.cdk(['synth', '--unstable=telemetry', `--telemetry-file=${telemetryFile}`], {
+      allowErrExit: true,
+      modEnv: {
+        INTEG_STACK_SET: 'stage-with-errors',
+      },
+    });
+
+    expect(output).toContain('This is an error');
+
+    const json = fs.readJSONSync(telemetryFile);
+    expect(json).toEqual([
+      expect.objectContaining({
+        event: expect.objectContaining({
+          command: expect.objectContaining({
+            path: ['synth'],
+            parameters: {
+              verbose: 1,
+              unstable: '<redacted>',
+              ['telemetry-file']: '<redacted>',
+              lookups: true,
+              ['ignore-errors']: false,
+              json: false,
+              debug: false,
+              staging: true,
+              notices: true,
+              ['no-color']: false,
+              ci: expect.anything(), // changes based on where this is called
+              validation: true,
+              quiet: false,
+            },
+            config: {
+              context: {},
+            },
+          }),
+          state: 'SUCCEEDED',
+          eventType: 'SYNTH',
+        }),
+        identifiers: expect.objectContaining({
+          installationId: expect.anything(),
+          sessionId: expect.anything(),
+          telemetryVersion: '1.0',
+          cdkCliVersion: expect.anything(),
+          cdkLibraryVersion: fixture.library.requestedVersion(),
+          region: expect.anything(),
+          eventId: expect.stringContaining(':1'),
+          timestamp: expect.anything(),
+        }),
+        environment: {
+          ci: expect.anything(),
+          os: {
+            platform: expect.anything(),
+            release: expect.anything(),
+          },
+          nodeVersion: expect.anything(),
+        },
+        project: {},
+        duration: {
+          total: expect.anything(),
+        },
+      }),
+      expect.objectContaining({
+        event: expect.objectContaining({
+          command: expect.objectContaining({
+            path: ['synth'],
+            parameters: {
+              verbose: 1,
+              unstable: '<redacted>',
+              ['telemetry-file']: '<redacted>',
+              lookups: true,
+              ['ignore-errors']: false,
+              json: false,
+              debug: false,
+              staging: true,
+              notices: true,
+              ['no-color']: false,
+              ci: expect.anything(), // changes based on where this is called
+              validation: true,
+              quiet: false,
+            },
+            config: {
+              context: {},
+            },
+          }),
+          state: 'FAILED',
+          eventType: 'INVOKE',
+        }),
+        identifiers: expect.objectContaining({
+          installationId: expect.anything(),
+          sessionId: expect.anything(),
+          telemetryVersion: '1.0',
+          cdkCliVersion: expect.anything(),
+          cdkLibraryVersion: fixture.library.requestedVersion(),
+          region: expect.anything(),
+          eventId: expect.stringContaining(':2'),
+          timestamp: expect.anything(),
+        }),
+        environment: {
+          ci: expect.anything(),
+          os: {
+            platform: expect.anything(),
+            release: expect.anything(),
+          },
+          nodeVersion: expect.anything(),
+        },
+        project: {},
+        duration: {
+          total: expect.anything(),
+        },
+        error: {
+          name: 'AssemblyError',
+        },
+      }),
+    ]);
+    fs.unlinkSync(telemetryFile);
+  }),
+);
+

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/synth/cdk-synth-telemetry.integtest.ts

@@ -0,0 +1,117 @@
+import * as path from 'path';
+import * as fs from 'fs-extra';
+import { integTest, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'cdk synth with telemetry data',
+  withDefaultFixture(async (fixture) => {
+    const telemetryFile = path.join(fixture.integTestDir, `telemetry-${Date.now()}.json`);
+    await fixture.cdk(['synth', fixture.fullStackName('test-1'), '--unstable=telemetry', `--telemetry-file=${telemetryFile}`]);
+    const json = fs.readJSONSync(telemetryFile);
+    expect(json).toEqual([
+      expect.objectContaining({
+        event: expect.objectContaining({
+          command: expect.objectContaining({
+            path: ['synth', '$STACKS_1'],
+            parameters: {
+              verbose: 1,
+              unstable: '<redacted>',
+              ['telemetry-file']: '<redacted>',
+              lookups: true,
+              ['ignore-errors']: false,
+              json: false,
+              debug: false,
+              staging: true,
+              notices: true,
+              ['no-color']: false,
+              ci: expect.anything(), // changes based on where this is called
+              validation: true,
+              quiet: false,
+            },
+            config: {
+              context: {},
+            },
+          }),
+          state: 'SUCCEEDED',
+          eventType: 'SYNTH',
+        }),
+        // some of these can change; but we assert that some value is recorded
+        identifiers: expect.objectContaining({
+          installationId: expect.anything(),
+          sessionId: expect.anything(),
+          telemetryVersion: '1.0',
+          cdkCliVersion: expect.anything(),
+          cdkLibraryVersion: fixture.library.requestedVersion(),
+          region: expect.anything(),
+          eventId: expect.stringContaining(':1'),
+          timestamp: expect.anything(),
+        }),
+        environment: {
+          ci: expect.anything(),
+          os: {
+            platform: expect.anything(),
+            release: expect.anything(),
+          },
+          nodeVersion: expect.anything(),
+        },
+        project: {},
+        duration: {
+          total: expect.anything(),
+        },
+      }),
+      expect.objectContaining({
+        event: expect.objectContaining({
+          command: expect.objectContaining({
+            path: ['synth', '$STACKS_1'],
+            parameters: {
+              verbose: 1,
+              unstable: '<redacted>',
+              ['telemetry-file']: '<redacted>',
+              lookups: true,
+              ['ignore-errors']: false,
+              json: false,
+              debug: false,
+              staging: true,
+              notices: true,
+              ['no-color']: false,
+              ci: expect.anything(), // changes based on where this is called
+              validation: true,
+              quiet: false,
+            },
+            config: {
+              context: {},
+            },
+          }),
+          state: 'SUCCEEDED',
+          eventType: 'INVOKE',
+        }),
+        identifiers: expect.objectContaining({
+          installationId: expect.anything(),
+          sessionId: expect.anything(),
+          telemetryVersion: '1.0',
+          cdkCliVersion: expect.anything(),
+          cdkLibraryVersion: fixture.library.requestedVersion(),
+          region: expect.anything(),
+          eventId: expect.stringContaining(':2'),
+          timestamp: expect.anything(),
+        }),
+        environment: {
+          ci: expect.anything(),
+          os: {
+            platform: expect.anything(),
+            release: expect.anything(),
+          },
+          nodeVersion: expect.anything(),
+        },
+        project: {},
+        duration: {
+          total: expect.anything(),
+        },
+      }),
+    ]);
+    fs.unlinkSync(telemetryFile);
+  }),
+);
+

packages/aws-cdk/README.md

@@ -1254,6 +1254,20 @@ cdk gc --unstable=gc
 The command will fail if `--unstable=gc` is not passed in, which acknowledges that the user
 is aware of the caveats in place for the feature.
 
+### `telemetry-file`
+
+Send your telemetry data to a local file (note that `--telemetry-file` is unstable, and must
+be passed in conjunction with `--unstable=telemetry`).
+
+```bash
+cdk list --telemetry-file=my/file/path --unstable=telemetry
+```
+
+The supplied path must be a non existing file. If the file exists, it will fail to log telemetry
+data but the command itself will continue uninterrupted.
+
+> Note: The file will be written to regardless of your opt-out status.
+
 ## Notices
 
 CDK Notices are important messages regarding security vulnerabilities, regressions, and usage of unsupported

packages/aws-cdk/lib/cli/cli-config.ts

@@ -42,6 +42,7 @@ export async function makeConfig(): Promise<CliConfig> {
       'no-color': { type: 'boolean', desc: 'Removes colors and other style from console output', default: false },
       'ci': { type: 'boolean', desc: 'Force CI detection. If CI=true then logs will be sent to stdout instead of stderr', default: YARGS_HELPERS.isCI() },
       'unstable': { type: 'array', desc: 'Opt in to unstable features. The flag indicates that the scope and API of a feature might still change. Otherwise the feature is generally production ready and fully supported. Can be specified multiple times.', default: [] },
+      'telemetry-file': { type: 'string', desc: 'Send telemetry data to a local file.', default: undefined },
     },
     commands: {
       'list': {

packages/aws-cdk/lib/cli/cli-type-registry.json

@@ -122,6 +122,10 @@
       "type": "array",
       "desc": "Opt in to unstable features. The flag indicates that the scope and API of a feature might still change. Otherwise the feature is generally production ready and fully supported. Can be specified multiple times.",
       "default": []
+    },
+    "telemetry-file": {
+      "type": "string",
+      "desc": "Send telemetry data to a local file."
     }
   },
   "commands": {

packages/aws-cdk/lib/cli/cli.ts

@@ -31,6 +31,8 @@ import { getMigrateScanType } from '../commands/migrate';
 import { execProgram, CloudExecutable } from '../cxapp';
 import type { StackSelector, Synthesizer } from '../cxapp';
 import { ProxyAgentProvider } from './proxy-agent';
+import { cdkCliErrorName } from './telemetry/error';
+import type { ErrorDetails } from './telemetry/schema';
 import { isDeveloperBuildVersion, versionWithBuild, versionNumber } from './version';
 
 if (!process.stdout.isTTY) {
@@ -97,6 +99,12 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
     caBundlePath: configuration.settings.get(['caBundlePath']),
   });
 
+  try {
+    await ioHost.startTelemetry(argv, configuration.context);
+  } catch (e: any) {
+    await ioHost.asIoHelper().defaults.trace(`Telemetry instantiation failed: ${e.message}`);
+  }
+
   const shouldDisplayNotices = configuration.settings.get(['notices']);
   // Notices either go to stderr, or nowhere
   ioHost.noticesDestination = shouldDisplayNotices ? 'stderr' : 'drop';
@@ -125,6 +133,12 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
     pluginHost: GLOBAL_PLUGIN_HOST,
   }, configuration.settings.get(['profile']));
 
+  try {
+    await ioHost.telemetry?.attachRegion(sdkProvider.defaultRegion);
+  } catch (e: any) {
+    await ioHost.asIoHelper().defaults.trace(`Telemetry attach region failed: ${e.message}`);
+  }
+
   let outDirLock: IReadLock | undefined;
   const cloudExecutable = new CloudExecutable({
     configuration,
@@ -195,6 +209,10 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
       throw new ToolkitError('You must either specify a list of Stacks or the `--all` argument');
     }
 
+    if (args['telemetry-file'] && !configuration.settings.get(['unstable']).includes('telemetry')) {
+      throw new ToolkitError('Unstable feature use: \'telemetry-file\' is unstable. It must be opted in via \'--unstable\', e.g. \'cdk deploy --unstable=telemetry --telemetry-file=my/file/path\'');
+    }
+
     args.STACKS = args.STACKS ?? (args.STACK ? [args.STACK] : []);
     args.ENVIRONMENTS = args.ENVIRONMENTS ?? [];
 
@@ -648,17 +666,28 @@ function determineHotswapMode(hotswap?: boolean, hotswapFallback?: boolean, watc
 
 /* c8 ignore start */ // we never call this in unit tests
 export function cli(args: string[] = process.argv.slice(2)) {
+  let error: ErrorDetails | undefined;
   exec(args)
     .then(async (value) => {
       if (typeof value === 'number') {
         process.exitCode = value;
       }
     })
-    .catch((err) => {
+    .catch(async (err) => {
       // Log the stack trace if we're on a developer workstation. Otherwise this will be into a minified
       // file and the printed code line and stack trace are huge and useless.
       prettyPrintError(err, isDeveloperBuildVersion());
+      error = {
+        name: cdkCliErrorName(err.name),
+      };
       process.exitCode = 1;
+    })
+    .finally(async () => {
+      try {
+        await CliIoHost.get()?.telemetry?.end(error);
+      } catch (e: any) {
+        await CliIoHost.get()?.asIoHelper().defaults.trace(`Ending Telemetry failed: ${e.message}`);
+      }
     });
 }
 /* c8 ignore stop */

packages/aws-cdk/lib/cli/convert-to-user-input.ts

@@ -34,6 +34,7 @@ export function convertYargsToUserInput(args: any): UserInput {
     noColor: args.noColor,
     ci: args.ci,
     unstable: args.unstable,
+    telemetryFile: args.telemetryFile,
   };
   let commandOptions;
   switch (args._[0] as Command) {
@@ -325,6 +326,7 @@ export function convertConfigToUserInput(config: any): UserInput {
     noColor: config.noColor,
     ci: config.ci,
     unstable: config.unstable,
+    telemetryFile: config.telemetryFile,
   };
   const listOptions = {
     long: config.list?.long,