feat(cli): send telemetry events to local file

packages/@aws-cdk/toolkit-lib/lib/api/io/private/messages.ts

@@ -17,7 +17,7 @@ import type { StackRollbackProgress } from '../../../payloads/rollback';
 import type { MfaTokenRequest, SdkTrace } from '../../../payloads/sdk';
 import type { StackActivity, StackMonitoringControlEvent } from '../../../payloads/stack-activity';
 import type { StackSelectionDetails } from '../../../payloads/synth';
-import type { AssemblyData, ConfirmationRequest, ContextProviderMessageSource, Duration, ErrorPayload, SingleStack, StackAndAssemblyData } from '../../../payloads/types';
+import type { AssemblyData, ConfirmationRequest, ContextProviderMessageSource, Duration, ErrorPayload, SingleStack, StackAndAssemblyData, Telemetry } from '../../../payloads/types';
 import type { FileWatchEvent, WatchSettings } from '../../../payloads/watch';
 
 /**
@@ -33,6 +33,12 @@ export const IO = {
     description: 'Credential plugin warnings',
   }),
 
+  CDK_TOOLKIT_I0050: make.debug<Telemetry>({
+    code: 'CDK_TOOLKIT_I0050',
+    description: 'Generic Telemetric Event',
+    interface: 'Telemetry',
+  }),
+
   // 1: Synth (1xxx)
   CDK_TOOLKIT_I1000: make.info<Duration>({
     code: 'CDK_TOOLKIT_I1000',

packages/@aws-cdk/toolkit-lib/lib/payloads/types.ts

@@ -70,6 +70,19 @@ export interface SingleStack {
   readonly stack: cxapi.CloudFormationStackArtifact;
 }
 
+export interface Telemetry {
+  readonly telemetry: {
+    readonly eventType: string,
+    readonly state: 'SUCCEEDED' | 'FAILED' | 'ABORTED';
+    readonly duration: number,
+    readonly error?: {
+      readonly name?: string;
+      readonly trace?: string;
+      readonly logs?: string;
+    },
+  }
+}
+
 /**
  * Duration information returned in the payload of an IO Message.
  */

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

@@ -13,7 +13,7 @@ import { GLOBAL_PLUGIN_HOST } from './singleton-plugin-host';
 import type { Command } from './user-configuration';
 import { Configuration } from './user-configuration';
 import * as version from './version';
-import { asIoHelper } from '../../lib/api-private';
+import { asIoHelper, IO } from '../../lib/api-private';
 import type { IReadLock } from '../api';
 import { ToolkitInfo, Notices } from '../api';
 import { SdkProvider, IoHostSdkLogger, setSdkTracing, sdkRequestHandler } from '../api/aws-auth';
@@ -88,6 +88,13 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
   });
   await configuration.load();
 
+  if (process.env.TELEMETRY_TEST_ENV) {
+    ioHost.bindTelemetryClient(
+      argv,
+      configuration.context.all,
+    );
+  }
+
   const ioHelper = asIoHelper(ioHost, ioHost.currentAction as any);
 
   // Always create and use ProxyAgent to support configuration via env vars
@@ -613,17 +620,58 @@ 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)) {
+  const startTime = new Date().getTime();
   exec(args)
     .then(async (value) => {
       if (typeof value === 'number') {
         process.exitCode = value;
       }
+      if (process.env.TELEMETRY_TEST_ENV) {
+        if (value === 1) {
+          await failedTelemetryExitEvent(args, startTime);
+        } else {
+          await successfulTelemetryExitEvent(args, startTime);
+        }
+      }
     })
-    .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, version.isDeveloperBuild());
+      if (process.env.TELEMETRY_TEST_ENV) {
+        await failedTelemetryExitEvent(args, startTime, err);
+      }
       process.exitCode = 1;
     });
 }
 /* c8 ignore stop */
+
+async function successfulTelemetryExitEvent(args: string[], startTime: number) {
+  await CliIoHost.instance().asIoHelper().notify(IO.CDK_TOOLKIT_I0050.msg(
+    `Exiting ${args[1]}`,
+    {
+      telemetry: {
+        duration: new Date().getTime() - startTime,
+        eventType: 'Exit',
+        state: 'SUCCEEDED',
+      },
+    },
+  ));
+}
+
+async function failedTelemetryExitEvent(args: string[], startTime: number, err?: any) {
+  await CliIoHost.instance().asIoHelper().notify(IO.CDK_TOOLKIT_I0050.msg(
+    `Exiting ${args[1]}`,
+    {
+      telemetry: {
+        duration: new Date().getTime() - startTime,
+        eventType: 'Exit',
+        state: 'FAILED',
+        error: {
+          name: err?.name ?? 'ExitCode1Error', // TODO: sanitize
+          // message: err.message, // TODO: sanitize
+        },
+      },
+    },
+  ));
+}

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

@@ -7,6 +7,16 @@ import * as promptly from 'promptly';
 import type { IoHelper, ActivityPrinterProps, IActivityPrinter } from '../../../lib/api-private';
 import { asIoHelper, IO, isMessageRelevantForLevel, CurrentActivityPrinter, HistoryActivityPrinter } from '../../../lib/api-private';
 import { StackActivityProgress } from '../../commands/deploy';
+import type { ITelemetryClient } from '../telemetry/client-interface';
+import type { SessionSchema } from '../telemetry/schema';
+import { randomUUID } from 'node:crypto';
+import * as version from './../version';
+import { IoHostTelemetryClient } from '../telemetry/io-host-client';
+import { getInstallationId } from '../telemetry/installation-id';
+import { makeConfig } from '../cli-config';
+import { sanitizeCommandLineArguments, sanitizeContext } from '../telemetry/sanitation-utils';
+import { AccountIdFetcher } from '../telemetry/account-id-fetcher';
+import { RegionFetcher } from '../telemetry/region-fetcher';
 
 export type { IIoHost, IoMessage, IoMessageCode, IoMessageLevel, IoRequest };
 
@@ -144,6 +154,10 @@ export class CliIoHost implements IIoHost {
   private corkedCounter = 0;
   private readonly corkedLoggingBuffer: IoMessage<unknown>[] = [];
 
+  private telemetryClient?: ITelemetryClient;
+  private telemetryInfo?: SessionSchema;
+  private telemetryCount = 0;
+
   private constructor(props: CliIoHostProps = {}) {
     this.currentAction = props.currentAction ?? 'none';
     this.isTTY = props.isTTY ?? process.stdout.isTTY ?? false;
@@ -154,6 +168,45 @@ export class CliIoHost implements IIoHost {
     this.stackProgress = props.stackProgress ?? StackActivityProgress.BAR;
   }
 
+  /**
+   * Required for telemetry
+   */
+  public async bindTelemetryClient(argv: any, context: {[key: string]: any}) {
+    // TODO: change this to EndpointTelemetryClient
+    this.telemetryClient = new IoHostTelemetryClient({
+      ioHost: this,
+    });
+
+    // sanitize the raw cli input
+    const command = sanitizeCommandLineArguments(argv, await makeConfig());
+    this.telemetryInfo = {
+      identifiers: {
+        installationId: getInstallationId(this.asIoHelper()),
+        sessionId: randomUUID(),
+        telemetryVersion: '1.0',
+        cdkCliVersion: version.versionNumber(),
+        accountId: await new AccountIdFetcher().fetch(),
+        region: await new RegionFetcher().fetch(),
+      },
+      event: {
+        command: {
+          path: command.path,
+          parameters: command.parameters,
+          config: sanitizeContext(context),
+        },
+      },
+      environment: {
+        ci: Boolean(process.env.CI),
+        os: {
+          platform: process.platform,
+          release: process.release.name,
+        },
+        nodeVersion: process.version,
+      },
+      project: {},
+    };
+  }
+
   /**
    * Returns the singleton instance
    */
@@ -248,6 +301,16 @@ export class CliIoHost implements IIoHost {
       return this._internalIoHost.notify(msg);
     }
 
+    if (process.env.TELEMETRY_TEST_ENV) {
+      try {
+        if (this.isTelemetryMessage(msg)) {
+          await this.emitTelemetry(msg);
+        }
+      } catch (e: any) {
+        this.defaults.debug(`Emit Telemetry Failed ${e.message}`);
+      }
+    }
+
     if (this.isStackActivity(msg)) {
       if (!this.activityPrinter) {
         this.activityPrinter = this.makeActivityPrinter();
@@ -270,6 +333,42 @@ export class CliIoHost implements IIoHost {
     stream?.write(output);
   }
 
+  private isTelemetryMessage(msg: IoMessage<any>) {
+    return msg.data && msg.data.telemetry;
+  }
+
+  private async emitTelemetry(msg: IoMessage<any>) {
+    // Session has not been attached
+    if (!this.telemetryInfo) { 
+      throw new ToolkitError('Session must be attached before telemetry is emitted');
+    }
+
+    const event = msg.data.telemetry;
+    await this.telemetryClient?.emit({
+      event: {
+        command: this.telemetryInfo.event.command,
+        state: event.state,
+        eventType: event.eventType,
+      },
+      identifiers: {
+        ...this.telemetryInfo.identifiers,
+        eventId: `${this.telemetryInfo.identifiers.sessionId}:${this.telemetryCount}`,
+        timestamp: new Date().toISOString(),
+      },
+      environment: this.telemetryInfo.environment,
+      project: this.telemetryInfo.project,
+      duration: {
+        total: event.duration,
+      },
+      ...(event.error ? {
+        error: {
+          name: event.error.name,
+        },
+      } : {}),
+    });
+    this.telemetryCount+=1;
+  }
+
   /**
    * Detect stack activity messages so they can be send to the printer.
    */

packages/aws-cdk/lib/cli/telemetry/account-id-fetcher.ts

@@ -0,0 +1,54 @@
+import {
+  GetCallerIdentityCommand,
+  GetCallerIdentityCommandOutput,
+  STSClient,
+} from '@aws-sdk/client-sts';
+import { v5 as uuidV5 } from 'uuid';
+
+// eslint-disable-next-line spellcheck/spell-checker
+const CDK_CLI_UUID_NAMESPACE = 'f47ac10b-58cc-4372-a567-0e02b2c3d479'; // A random v4 UUID
+
+/**
+ * Retrieves the account ID of the user
+ */
+export class AccountIdFetcher {
+  private accountIdPromise?: Promise<GetCallerIdentityCommandOutput>;
+  /**
+   * constructor for AccountIdFetcher
+   */
+  constructor(private readonly stsClient = new STSClient()) {}
+  fetch = async () => {
+    if (this.accountIdPromise) {
+      try {
+        const stsResponse = await this.accountIdPromise;
+        return this.getAccountIdFromStsResponse(stsResponse);
+      } catch {
+        // We failed to get the account Id. Most likely the user doesn't have credentials
+        return;
+      }
+    }
+    try {
+      this.accountIdPromise = this.stsClient.send(
+        new GetCallerIdentityCommand({}),
+      );
+      const stsResponse = await this.accountIdPromise;
+      return this.getAccountIdFromStsResponse(stsResponse);
+    } catch {
+      // We failed to get the account Id. Most likely the user doesn't have credentials
+      return;
+    }
+  };
+
+  private getAccountIdFromStsResponse = (
+    stsResponse: GetCallerIdentityCommandOutput,
+  ) => {
+    if (stsResponse && stsResponse.Account) {
+      return uuidV5(
+        stsResponse.Account,
+        CDK_CLI_UUID_NAMESPACE,
+      );
+    }
+    // We failed to get the account Id. Most likely the user doesn't have credentials
+    return;
+  };
+}

packages/aws-cdk/lib/cli/telemetry/client-interface.ts

@@ -0,0 +1,14 @@
+import type { TelemetrySchema } from './schema';
+
+/**
+ * Interface for all Telemetry Clients.
+ *
+ * A telemtry client receives event data and determines
+ * when and where to send it.
+ */
+export interface ITelemetryClient {
+  /**
+   * Send data to the client
+   */
+  emit(event: TelemetrySchema): Promise<boolean>;
+}