chore(cli): telemetry sink

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

@@ -0,0 +1,140 @@
+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 = 2_000;
+
+/**
+ * Properties for the Endpoint Telemetry Client
+ */
+export interface EndpointTelemetryClientProps {
+  /**
+   * 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 EndpointTelemetryClient implements ITelemetrySink {
+  private events: TelemetrySchema[] = [];
+  private endpoint: UrlWithStringQuery;
+  private ioHost: IoHelper;
+  private agent?: Agent;
+
+  public constructor(props: EndpointTelemetryClientProps) {
+    this.endpoint = props.endpoint;
+    this.ioHost = 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.ioHost.defaults.warn(`Failed to add telemetry event: ${e.message}`);
+    }
+  }
+
+  public async flush(): Promise<void> {
+    if (this.events.length === 0) {
+      return;
+    }
+
+    try {
+      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, and error message was previously logged to ioHost
+    }
+  }
+
+  /**
+   * Returns true if telemetry successfully posted, false otherwise.
+   */
+  private async https(
+    url: UrlWithStringQuery,
+    body: TelemetrySchema[],
+  ): Promise<boolean> {
+    try {
+      const res = await requestPromise(url, body, this.agent);
+
+      // Successfully posted
+      if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+        return true;
+      }
+
+      await this.ioHost.defaults.debug(`Telemetry Unsuccessful: POST ${url.hostname}${url.pathname}: ${res.statusCode}:${res.statusMessage}`);
+
+      return false;
+    } catch (e: any) {
+      await this.ioHost.defaults.debug(`Telemetry Error: POST ${url.hostname}${url.pathname}: ${JSON.stringify(e)}`);
+      return false;
+    }
+  }
+}
+
+/**
+ * A Promisified version of `https.request()`
+ */
+function requestPromise(
+  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-client.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 FileTelemetryClientProps {
+  /**
+   * 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 FileTelemetryClient implements ITelemetrySink {
+  private ioHelper: IoHelper;
+  private logFilePath: string;
+
+  /**
+   * Create a new FileTelemetryClient
+   */
+  constructor(props: FileTelemetryClientProps) {
+    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);
+
+      // Write to file
+      fs.appendFileSync(this.logFilePath, output);
+    } catch (e: any) {
+      // Never throw errors, just log them via ioHost
+      await this.ioHelper.defaults.warn(`Failed to add telemetry event: ${e.message}`);
+    }
+  }
+
+  public async flush(): Promise<void> {
+    return;
+  }
+}

packages/aws-cdk/lib/cli/telemetry/io-host-client.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 IoHostTelemetryClientProps {
+  /**
+   * Where messages are going to be sent
+   */
+  readonly ioHost: IIoHost;
+}
+
+/**
+ * A telemetry client that collects events and flushes them to stdout.
+ */
+export class IoHostTelemetryClient implements ITelemetrySink {
+  private ioHelper: IoHelper;
+
+  /**
+   * Create a new StdoutTelemetryClient
+   */
+  constructor(props: IoHostTelemetryClientProps) {
+    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>;
+}

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

@@ -0,0 +1,23 @@
+import type { UrlWithStringQuery } from 'node:url';
+import { parse } from 'node:url';
+
+let cachedUrl: UrlWithStringQuery;
+
+let prodUrl: string = ''; // TODO: add when its launched
+
+/**
+ *  Usage data tracking service URL
+ */
+export const getUrl = (): UrlWithStringQuery => {
+  if (!cachedUrl) {
+    cachedUrl = getParsedUrl();
+  }
+
+  return cachedUrl;
+};
+
+const getParsedUrl = (): UrlWithStringQuery => {
+  return parse(
+    process.env.CDK_TELEMETRY_ENDPOINT || prodUrl,
+  );
+};