chore(cli): telemetry sink (#585)

Introduces a generic telemetry sink to the cli. it is tested but not
used anywhere.

There are 3 base types of telemetry sinks:

- `FileSink` -> gathers events and writes them to a file 
- `IoHostSink` -> gathers events and sends them to the IoHost (for
writing to stdout/err)
- `EndpointSink` -> gathers events and sends them to an external
endpoint, batching at intervals of 30 seconds.



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

Author: kaizencc

packages/aws-cdk/lib/cli/telemetry/endpoint-sink.ts

@@ -0,0 +1,141 @@
+import type { IncomingMessage } from 'http';
+import type { Agent } from 'https';
+import { request } from 'https';
+import type { UrlWithStringQuery } from 'url';
+import { ToolkitError } from '@aws-cdk/toolkit-lib';
+import { IoHelper } from '../../api-private';
+import type { IIoHost } from '../io-host';
+import type { TelemetrySchema } from './schema';
+import type { ITelemetrySink } from './sink-interface';
+
+const REQUEST_ATTEMPT_TIMEOUT_MS = 500;
+
+/**
+ * Properties for the Endpoint Telemetry Client
+ */
+export interface EndpointTelemetrySinkProps {
+  /**
+   * The external endpoint to hit
+   */
+  readonly endpoint: UrlWithStringQuery;
+
+  /**
+   * Where messages are going to be sent
+   */
+  readonly ioHost: IIoHost;
+
+  /**
+   * The agent responsible for making the network requests.
+   *
+   * Use this to set up a proxy connection.
+   *
+   * @default - Uses the shared global node agent
+   */
+  readonly agent?: Agent;
+}
+
+/**
+ * The telemetry client that hits an external endpoint.
+ */
+export class EndpointTelemetrySink implements ITelemetrySink {
+  private events: TelemetrySchema[] = [];
+  private endpoint: UrlWithStringQuery;
+  private ioHelper: IoHelper;
+  private agent?: Agent;
+
+  public constructor(props: EndpointTelemetrySinkProps) {
+    this.endpoint = props.endpoint;
+    this.ioHelper = IoHelper.fromActionAwareIoHost(props.ioHost);
+    this.agent = props.agent;
+
+    // Batch events every 30 seconds
+    setInterval(() => this.flush(), 30000).unref();
+  }
+
+  /**
+   * Add an event to the collection.
+   */
+  public async emit(event: TelemetrySchema): Promise<void> {
+    try {
+      this.events.push(event);
+    } catch (e: any) {
+      // Never throw errors, just log them via ioHost
+      await this.ioHelper.defaults.trace(`Failed to add telemetry event: ${e.message}`);
+    }
+  }
+
+  public async flush(): Promise<void> {
+    try {
+      if (this.events.length === 0) {
+        return;
+      }
+
+      const res = await this.https(this.endpoint, this.events);
+
+      // Clear the events array after successful output
+      if (res) {
+        this.events = [];
+      }
+    } catch (e: any) {
+      // Never throw errors, just log them via ioHost
+      await this.ioHelper.defaults.trace(`Failed to add telemetry event: ${e.message}`);
+    }
+  }
+
+  /**
+   * Returns true if telemetry successfully posted, false otherwise.
+   */
+  private async https(
+    url: UrlWithStringQuery,
+    body: TelemetrySchema[],
+  ): Promise<boolean> {
+    try {
+      const res = await doRequest(url, body, this.agent);
+
+      // Successfully posted
+      if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+        return true;
+      }
+
+      await this.ioHelper.defaults.trace(`Telemetry Unsuccessful: POST ${url.hostname}${url.pathname}: ${res.statusCode}:${res.statusMessage}`);
+
+      return false;
+    } catch (e: any) {
+      await this.ioHelper.defaults.trace(`Telemetry Error: POST ${url.hostname}${url.pathname}: ${JSON.stringify(e)}`);
+      return false;
+    }
+  }
+}
+
+/**
+ * A Promisified version of `https.request()`
+ */
+function doRequest(
+  url: UrlWithStringQuery,
+  data: TelemetrySchema[],
+  agent?: Agent,
+) {
+  return new Promise<IncomingMessage>((ok, ko) => {
+    const payload: string = JSON.stringify(data);
+    const req = request({
+      hostname: url.hostname,
+      port: url.port,
+      path: url.pathname,
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'content-length': payload.length,
+      },
+      agent,
+      timeout: REQUEST_ATTEMPT_TIMEOUT_MS,
+    }, ok);
+
+    req.on('error', ko);
+    req.on('timeout', () => {
+      const error = new ToolkitError(`Timeout after ${REQUEST_ATTEMPT_TIMEOUT_MS}ms, aborting request`);
+      req.destroy(error);
+    });
+
+    req.end(payload);
+  });
+}

packages/aws-cdk/lib/cli/telemetry/file-sink.ts

@@ -0,0 +1,67 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ToolkitError, type IIoHost } from '@aws-cdk/toolkit-lib';
+import type { TelemetrySchema } from './schema';
+import type { ITelemetrySink } from './sink-interface';
+import { IoHelper } from '../../api-private';
+
+/**
+ * Properties for the FileTelemetryClient
+ */
+export interface FileTelemetrySinkProps {
+  /**
+   * Where messages are going to be sent
+   */
+  readonly ioHost: IIoHost;
+
+  /**
+   * The local file to log telemetry data to.
+   */
+  readonly logFilePath: string;
+}
+
+/**
+ * A telemetry client that collects events writes them to a file
+ */
+export class FileTelemetrySink implements ITelemetrySink {
+  private ioHelper: IoHelper;
+  private logFilePath: string;
+
+  /**
+   * Create a new FileTelemetryClient
+   */
+  constructor(props: FileTelemetrySinkProps) {
+    this.ioHelper = IoHelper.fromActionAwareIoHost(props.ioHost);
+    this.logFilePath = props.logFilePath;
+
+    if (fs.existsSync(this.logFilePath)) {
+      throw new ToolkitError(`Telemetry file already exists at ${this.logFilePath}`);
+    }
+
+    // Create the file if necessary
+    const directory = path.dirname(this.logFilePath);
+    if (!fs.existsSync(directory)) {
+      fs.mkdirSync(directory, { recursive: true });
+    }
+  }
+
+  /**
+   * Emit an event.
+   */
+  public async emit(event: TelemetrySchema): Promise<void> {
+    try {
+      // Format the events as a JSON string with pretty printing
+      const output = JSON.stringify(event, null, 2) + '\n';
+
+      // Write to file
+      fs.appendFileSync(this.logFilePath, output);
+    } catch (e: any) {
+      // Never throw errors, just log them via ioHost
+      await this.ioHelper.defaults.trace(`Failed to add telemetry event: ${e.message}`);
+    }
+  }
+
+  public async flush(): Promise<void> {
+    return;
+  }
+}

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

@@ -0,0 +1,48 @@
+import type { IIoHost } from '@aws-cdk/toolkit-lib';
+import type { TelemetrySchema } from './schema';
+import type { ITelemetrySink } from './sink-interface';
+import { IoHelper } from '../../api-private';
+
+/**
+ * Properties for the StdoutTelemetryClient
+ */
+export interface IoHostTelemetrySinkProps {
+  /**
+   * Where messages are going to be sent
+   */
+  readonly ioHost: IIoHost;
+}
+
+/**
+ * A telemetry client that collects events and flushes them to stdout.
+ */
+export class IoHostTelemetrySink implements ITelemetrySink {
+  private ioHelper: IoHelper;
+
+  /**
+   * Create a new StdoutTelemetryClient
+   */
+  constructor(props: IoHostTelemetrySinkProps) {
+    this.ioHelper = IoHelper.fromActionAwareIoHost(props.ioHost);
+  }
+
+  /**
+   * Emit an event
+   */
+  public async emit(event: TelemetrySchema): Promise<void> {
+    try {
+      // Format the events as a JSON string with pretty printing
+      const output = JSON.stringify(event, null, 2);
+
+      // Write to IoHost
+      await this.ioHelper.defaults.trace(`--- TELEMETRY EVENT ---\n${output}\n-----------------------\n`);
+    } catch (e: any) {
+      // Never throw errors, just log them via ioHost
+      await this.ioHelper.defaults.trace(`Failed to add telemetry event: ${e.message}`);
+    }
+  }
+
+  public async flush(): Promise<void> {
+    return;
+  }
+}

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

@@ -0,0 +1,63 @@
+interface Identifiers {
+  readonly cdkCliVersion: string;
+  readonly cdkLibraryVersion?: string;
+  readonly telemetryVersion: string;
+  readonly sessionId: string;
+  readonly eventId: string;
+  readonly installationId: string;
+  readonly timestamp: string;
+  readonly accountId?: string;
+  readonly region?: string;
+}
+
+interface Event {
+  readonly state: 'ABORTED' | 'FAILED' | 'SUCCEEDED';
+  readonly eventType: string;
+  readonly command: {
+    readonly path: string[];
+    readonly parameters: string[];
+    readonly config: { [key: string]: any };
+  };
+}
+
+interface Environment {
+  readonly os: {
+    readonly platform: string;
+    readonly release: string;
+  };
+  readonly ci: boolean;
+  readonly nodeVersion: string;
+}
+
+interface Duration {
+  readonly total: number;
+  readonly components?: { [key: string]: number };
+}
+
+type Counters = { [key: string]: number };
+
+interface Error {
+  readonly name: string;
+  readonly message?: string; // anonymized stack message
+  readonly trace?: string; // anonymized stack trace
+  readonly logs?: string; // anonymized stack logs
+}
+
+interface Dependency {
+  readonly name: string;
+  readonly version: string;
+}
+
+interface Project {
+  readonly dependencies?: Dependency[];
+}
+
+export interface TelemetrySchema {
+  readonly identifiers: Identifiers;
+  readonly event: Event;
+  readonly environment: Environment;
+  readonly project: Project;
+  readonly duration: Duration;
+  readonly counters?: Counters;
+  readonly error?: Error;
+}

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

@@ -0,0 +1,20 @@
+import type { TelemetrySchema } from './schema';
+
+/**
+ * All Telemetry Clients are Sinks.
+ *
+ * A telemtry client receives event data via 'emit'
+ * and sends batched events via 'flush'
+ */
+export interface ITelemetrySink {
+  /**
+   * Recieve an event
+   */
+  emit(event: TelemetrySchema): Promise<void>;
+
+  /**
+   * If the implementer of ITelemetrySink batches events,
+   * flush sends the data and clears the cache.
+   */
+  flush(): Promise<void>;
+}