refactor: switch to devtools shared tracking plan COMPASS-10801

package.json

@@ -42,7 +42,7 @@
     "preupdate-third-party-notices": "npm run -w packages/compass compile",
     "update-third-party-notices": "cp packages/compass/THIRD-PARTY-NOTICES.md .",
     "postupdate-third-party-notices": "npx prettier-compass THIRD-PARTY-NOTICES.md --write",
-    "update-tracking-plan": "npx ts-node scripts/generate-tracking-plan.ts > docs/tracking-plan.md",
+    "update-tracking-plan": "tracking-plan --events-file=packages/compass-telemetry/src/telemetry-events.ts --app-name=Compass > docs/tracking-plan.md",
     "postupdate-tracking-plan": "npx prettier-compass docs/tracking-plan.md --write",
     "bump-packages": "bump-monorepo-packages",
     "publish-packages": "lerna publish from-package --no-verify-access --no-push --no-git-tag-version --yes",
@@ -71,6 +71,7 @@
     "@mongodb-js/eslint-config-devtools": "^0.11.5",
     "@mongodb-js/monorepo-tools": "^1.5.7",
     "@mongodb-js/sbom-tools": "^0.10.18",
+    "@mongodb-js/tracking-plan": "^0.3.2",
     "@testing-library/dom": "^8.20.1",
     "ag-grid-react": "^20.2.0",
     "braintrust": "^2.2.2",

packages/compass-telemetry/src/index.ts

@@ -1,10 +1,7 @@
 export { createIpcTrack, createIpcSendTrack } from './ipc-track';
 export type { TelemetryServiceOptions } from './generic-track';
-export type {
-  TrackFunction,
-  IdentifyTraits,
-  ExtraConnectionData,
-} from './types';
+export type { TrackFunction, ExtraConnectionData } from './types';
+export type { IdentifyEvent } from './telemetry-events';
 
 export { CompassExperimentationProvider } from './experimentation-provider';
 export {

packages/compass-telemetry/src/telemetry-events.ts

@@ -1,97 +1,102 @@
 /**
- * Traits sent along with the Segment identify call
+ * The Segment identify call
+ *
+ * @category Identify
  */
-export type IdentifyTraits = {
-  /**
-   * Shortened version number (e.g., '1.29').
-   */
-  compass_version: string;
+export type IdentifyEvent = {
+  name: 'Identify';
+  payload: {
+    /**
+     * Shortened version number (e.g., '1.29').
+     */
+    compass_version: string;
 
-  /**
-   * The full version of the Compass application, including additional identifiers
-   * such as build metadata or pre-release tags (e.g., '1.29.0-beta.1').
-   */
-  compass_full_version: string;
+    /**
+     * The full version of the Compass application, including additional identifiers
+     * such as build metadata or pre-release tags (e.g., '1.29.0-beta.1').
+     */
+    compass_full_version: string;
 
-  /**
-   * The distribution of Compass being used.
-   */
-  compass_distribution: 'compass' | 'compass-readonly' | 'compass-isolated';
+    /**
+     * The distribution of Compass being used.
+     */
+    compass_distribution: 'compass' | 'compass-readonly' | 'compass-isolated';
 
-  /**
-   * The release channel of Compass.
-   * - 'stable' for the general release.
-   * - 'beta' for pre-release versions intended for testing.
-   * - 'dev' for development versions only distributed internally.
-   */
-  compass_channel: 'stable' | 'beta' | 'dev';
+    /**
+     * The release channel of Compass.
+     * - 'stable' for the general release.
+     * - 'beta' for pre-release versions intended for testing.
+     * - 'dev' for development versions only distributed internally.
+     */
+    compass_channel: 'stable' | 'beta' | 'dev';
 
-  /**
-   * The platform on which Compass is running, derived from Node.js `os.platform()`.
-   * Corresponds to the operating system (e.g., 'darwin' for macOS, 'win32' for Windows, 'linux' for Linux).
-   */
-  platform: string;
+    /**
+     * The platform on which Compass is running, derived from Node.js `os.platform()`.
+     * Corresponds to the operating system (e.g., 'darwin' for macOS, 'win32' for Windows, 'linux' for Linux).
+     */
+    platform: string;
 
-  /**
-   * The architecture of the system's processor, derived from Node.js `os.arch()`.
-   * 'x64' for 64-bit processors and 'arm' for ARM processors.
-   */
-  arch: string;
+    /**
+     * The architecture of the system's processor, derived from Node.js `os.arch()`.
+     * 'x64' for 64-bit processors and 'arm' for ARM processors.
+     */
+    arch: string;
 
-  /**
-   * The type of operating system, including specific operating system
-   * names or types (e.g., 'Linux', 'Windows_NT', 'Darwin').
-   */
-  os_type?: string;
+    /**
+     * The type of operating system, including specific operating system
+     * names or types (e.g., 'Linux', 'Windows_NT', 'Darwin').
+     */
+    os_type?: string;
 
-  /**
-   * Detailed kernel or system version information.
-   * Example: 'Darwin Kernel Version 21.4.0: Fri Mar 18 00:45:05 PDT 2022; root:xnu-8020.101.4~15/RELEASE_X86_64'.
-   */
-  os_version?: string;
+    /**
+     * Detailed kernel or system version information.
+     * Example: 'Darwin Kernel Version 21.4.0: Fri Mar 18 00:45:05 PDT 2022; root:xnu-8020.101.4~15/RELEASE_X86_64'.
+     */
+    os_version?: string;
 
-  /**
-   * The architecture of the operating system, if available, which might be more specific
-   * than the system's processor architecture (e.g., 'x86_64' for 64-bit architecture).
-   */
-  os_arch?: string;
+    /**
+     * The architecture of the operating system, if available, which might be more specific
+     * than the system's processor architecture (e.g., 'x86_64' for 64-bit architecture).
+     */
+    os_arch?: string;
 
-  /**
-   * The release identifier of the operating system.
-   * This can provide additional details about the operating system release or
-   * version (e.g. the kernel version for a specific macOS release).
-   *
-   * NOTE: This property helps determine the macOS version in use. The reported
-   * version corresponds to the Darwin kernel version, which can be mapped
-   * to the respective macOS release using the conversion table available at:
-   * https://en.wikipedia.org/wiki/MacOS_version_history.
-   */
-  os_release?: string;
+    /**
+     * The release identifier of the operating system.
+     * This can provide additional details about the operating system release or
+     * version (e.g. the kernel version for a specific macOS release).
+     *
+     * NOTE: This property helps determine the macOS version in use. The reported
+     * version corresponds to the Darwin kernel version, which can be mapped
+     * to the respective macOS release using the conversion table available at:
+     * https://en.wikipedia.org/wiki/MacOS_version_history.
+     */
+    os_release?: string;
 
-  /**
-   * The Linux distribution name, if running on a Linux-based operating system,
-   * derived by reading from `/etc/os-release`.
-   * Examples include 'ubuntu', 'debian', or 'rhel'.
-   */
-  os_linux_dist?: string;
+    /**
+     * The Linux distribution name, if running on a Linux-based operating system,
+     * derived by reading from `/etc/os-release`.
+     * Examples include 'ubuntu', 'debian', or 'rhel'.
+     */
+    os_linux_dist?: string;
 
-  /**
-   * The version of the Linux distribution, if running on a Linux-based operating system,
-   * derived by reading from `/etc/os-release`.
-   * Examples include '20.04' for Ubuntu or '10' for Debian.
-   */
-  os_linux_release?: string;
+    /**
+     * The version of the Linux distribution, if running on a Linux-based operating system,
+     * derived by reading from `/etc/os-release`.
+     * Examples include '20.04' for Ubuntu or '10' for Debian.
+     */
+    os_linux_release?: string;
+  };
 };
 
-export type CommonProperties = {
+export type CommonEventProperties = {
   is_compass_web?: true;
 };
 
 /**
  * All events in compass
  */
 type CommonEvent<E extends { payload: unknown }> = E & {
-  payload: E['payload'] & CommonProperties;
+  payload: E['payload'] & CommonEventProperties;
 };
 
 export type ConnectionScopedProperties = {
@@ -105,7 +110,7 @@ export type ConnectionScopedProperties = {
  * Events that are connection scoped are associated with one connection.
  */
 type ConnectionScopedEvent<E extends { payload: unknown }> = E & {
-  payload: E['payload'] & CommonProperties & ConnectionScopedProperties;
+  payload: E['payload'] & CommonEventProperties & ConnectionScopedProperties;
 };
 
 /**
@@ -4047,6 +4052,7 @@ export type TelemetryEvent =
   | FocusModeOpenedEvent
   | GuideCueDismissedEvent
   | GuideCueGroupDismissedEvent
+  | IdentifyEvent
   | ImportCompletedEvent
   | ImportErrorLogOpenedEvent
   | ImportOpenedEvent

packages/compass-telemetry/src/types.ts

@@ -2,11 +2,7 @@ import type {
   ConnectionScopedProperties,
   TelemetryEvent,
 } from './telemetry-events';
-export type {
-  TelemetryEvent,
-  IdentifyTraits,
-  ExtraConnectionData,
-} from './telemetry-events';
+export type { TelemetryEvent, ExtraConnectionData } from './telemetry-events';
 
 type TelemetryConnectionInfo = {
   id: string;

packages/compass/src/main/telemetry.ts

@@ -5,7 +5,7 @@ import { createLogger } from '@mongodb-js/compass-logging';
 import type { CompassApplication } from './application';
 import type { EventEmitter } from 'events';
 import { getOsInfo } from '@mongodb-js/get-os-info';
-import type { IdentifyTraits } from '@mongodb-js/compass-telemetry';
+import type { IdentifyEvent } from '@mongodb-js/compass-telemetry';
 import { getDeviceId } from '@mongodb-js/device-id';
 import { getMachineId } from 'native-machine-id';
 
@@ -52,7 +52,7 @@ class CompassTelemetry {
 
   private static initPromise: Promise<void> | null = null;
 
-  private static _getCommonProperties() {
+  private static _getCommonEventProperties() {
     // Used in both track and identify to add common traits
     // to any event that we send to segment
     return {
@@ -66,7 +66,7 @@ class CompassTelemetry {
 
   // Keep this method synchronous to avoid race conditions.
   private static _track(info: EventInfo) {
-    const commonProperties = this._getCommonProperties();
+    const commonProperties = this._getCommonEventProperties();
 
     if (!this.telemetryAnonymousId) {
       this.queuedEvents.push(info);
@@ -112,8 +112,8 @@ class CompassTelemetry {
       this.analytics &&
       this.telemetryAnonymousId
     ) {
-      const traits: IdentifyTraits = {
-        ...this._getCommonProperties(),
+      const traits: IdentifyEvent['payload'] = {
+        ...this._getCommonEventProperties(),
         platform: process.platform,
         arch: process.arch,
         ...this.osInfo,