feat(core): add analytics (#34144)

## Current Behavior

Nx CLI has no mechanism for collecting usage analytics, and users are
not prompted about their analytics preferences. There is no way for the
Nx team to understand which commands, generators, and features are most
used.

## Expected Behavior

This PR adds opt-in analytics collection to the Nx CLI with two main
components:

### 1. Analytics Prompt

Users are prompted for their analytics preference on first interactive
CLI run when `analytics` is not yet configured in `nx.json`:

- Only appears when `analytics` is undefined in `nx.json`
- Skipped in CI environments
- Skipped in non-interactive terminals (piped input/output)
- Stores the user's choice as a boolean (`true`/`false`) in the
`analytics` field of `nx.json`
- Defaults to `false` if the user cancels (Ctrl+C)
- Includes a migration (`update-22-6-0/enable-analytics-prompt`) for
existing workspaces

### 2. Analytics Collector

When analytics is enabled, the CLI collects usage data via a Rust-based
telemetry service and sends it to GA4. Data collected includes:

- **Commands run** (e.g. `build`, `test`, `generate`, `add`) — tracked
as page views
- **Command arguments** — with aggressive sanitization of sensitive
values (project names, file paths, URLs, credentials, free-form text are
all redacted; only boolean flags and safe enum values are preserved)
- **Generator and package names** for `nx add` and `nx generate` (as
custom dimensions)
- **Project graph creation duration**
- **Environment metadata**: Nx version, Node version, package manager,
OS, architecture, CI detection

### Workspace Identification

Each workspace is identified by a deterministic ID (used as the GA4
client ID) with the following priority:

1. **`nxCloudId`** (or `nxCloudAccessToken`) from `nx.json` — used
directly, most stable
2. **Git remote URL** (`git remote get-url origin`) — SHA-256 hashed for
privacy
3. **First commit SHA** (`git rev-list --max-parents=0 HEAD`) — used
directly as a fallback

Each user/machine is identified separately via `node-machine-id`.

### Privacy & Safety

- No project names, file paths, or other PII is collected
- Sensitive CLI arguments are redacted (see `SENSITIVE_ARGS_KEYS` list)
- Analytics is strictly opt-in (must be `true` in `nx.json`)
- Telemetry failures are silently ignored — never blocks or crashes the
CLI
- WASM builds are excluded (no native telemetry module available)
- The native telemetry functions are loaded with optional chaining to
prevent crashes when running against published Nx binaries that don't
include them yet

### Key Files

- `packages/nx/src/utils/analytics-prompt.ts` — Prompt logic and
workspace ID generation
- `packages/nx/src/analytics/analytics.ts` — Analytics collector, event
tracking, argument sanitization
- `packages/nx/src/native/telemetry/` — Rust telemetry service
(constants, service, mod)
- `packages/nx/src/utils/machine-id-cache.ts` — Machine ID for user
identification
- `packages/nx/src/migrations/update-22-6-0/enable-analytics-prompt.ts`
— Migration for existing workspaces

## Related Issue(s)

Closes NXC-3731
Closes NXC-3732
Closes NXC-3733
Closes NXC-3734

---------

Co-authored-by: nx-cloud[bot] <71083854+nx-cloud[bot]@users.noreply.github.com>
Co-authored-by: Coly010 <Coly010@users.noreply.github.com>
Co-authored-by: Jason Jean <jasonjean1993@gmail.com>

Author: 3 people

Cargo.lock

@@ -61,6 +61,8 @@ tracing-subscriber = { version = "0.3.17", features = ["env-filter"] }
 tokio-util = "0.7.9"
 tracing-appender = "0.2"
 tui-logger = { version = "0.17.2", features = ["tracing-support"] }
+urlencoding = "2.1"
+uuid = { version = "1.0", features = ["v4"] }
 tui-term = { git = "https://github.com/JamesHenry/tui-term", rev = "88e3b61425c97220c528ef76c188df10032a75dd" }
 walkdir = '2.3.3'
 xxhash-rust = { version = '0.8.5', features = ['xxh3', 'xxh64'] }

packages/nx/Cargo.toml

@@ -6,6 +6,7 @@ import { stripIndents } from '../src/utils/strip-indents';
 import { daemonClient } from '../src/daemon/client/client';
 import { prompt } from 'enquirer';
 import { output } from '../src/utils/output';
+import { flushAnalytics } from '../src/analytics';
 
 /**
  * Nx is being run inside a workspace.
@@ -56,6 +57,7 @@ export async function initLocal(workspace: WorkspaceTypeAndRoot) {
     }
   } catch (e) {
     console.error(e.message);
+    flushAnalytics();
     process.exit(1);
   }
 }

packages/nx/bin/init-local.ts

@@ -29,6 +29,8 @@ import { performance } from 'perf_hooks';
 import { setupWorkspaceContext } from '../src/utils/workspace-context';
 import { daemonClient } from '../src/daemon/client/client';
 import { removeDbConnections } from '../src/utils/db-connection';
+import { ensureAnalyticsPreferenceSet } from '../src/utils/analytics-prompt';
+import { flushAnalytics, startAnalytics } from '../src/analytics';
 
 async function main() {
   if (
@@ -102,6 +104,12 @@ async function main() {
       handleMissingLocalInstallation(workspace ? workspace.dir : null);
     }
 
+    // Prompt for analytics preference if not set
+    try {
+      await ensureAnalyticsPreferenceSet();
+    } catch {}
+    await startAnalytics();
+
     // this file is already in the local workspace
     if (isNxCloudCommand(process.argv[2])) {
       // nx-cloud commands can run without local Nx installation
@@ -313,5 +321,6 @@ process.on('exit', () => {
 
 main().catch((error) => {
   console.error(error);
+  flushAnalytics();
   process.exit(1);
 });

packages/nx/bin/nx.ts

@@ -148,6 +148,12 @@
       "version": "22.7.0-beta.0",
       "description": "Adds .nx/polygraph to .gitignore",
       "implementation": "./src/migrations/update-22-7-0/add-polygraph-to-git-ignore"
+    },
+    "22-6-0-enable-analytics-prompt": {
+      "cli": "nx",
+      "version": "22.6.0-beta.11",
+      "description": "Prompts to enable usage analytics",
+      "implementation": "./src/migrations/update-22-6-0/enable-analytics-prompt"
     }
   }
 }

packages/nx/migrations.json

@@ -142,6 +142,10 @@
       "type": "boolean",
       "description": "Specifies whether to add inference plugins when generating new projects."
     },
+    "analytics": {
+      "type": "boolean",
+      "description": "Set this to true to allow Nx to collect usage analytics."
+    },
     "release": {
       "type": "object",
       "description": "Configuration for the nx release commands.",

packages/nx/schemas/nx-schema.json

@@ -82,6 +82,7 @@ export const allowedWorkspaceExtensions = [
   'useDaemonProcess',
   'useInferencePlugins',
   'neverConnectToCloud',
+  'analytics',
   'sync',
   'useLegacyCache',
   'maxCacheSize',

packages/nx/src/adapter/compat.ts

@@ -0,0 +1,172 @@
+import { argsToQueryString } from './analytics';
+
+describe('argsToQueryString', () => {
+  it('should convert simple non-sensitive args to query string', () => {
+    const result = argsToQueryString({ verbose: true, parallel: 3 });
+    expect(result).toBe('verbose=true&parallel=3');
+  });
+
+  it('should handle array values by repeating the key', () => {
+    const result = argsToQueryString({
+      targets: ['build', 'test'],
+    });
+    expect(result).toBe('targets=build&targets=test');
+  });
+
+  it('should filter out internal yargs keys', () => {
+    const result = argsToQueryString({
+      verbose: true,
+      $0: 'nx',
+      _: ['run-many'],
+      __overrides_unparsed__: [],
+      __overrides__: [],
+    });
+    expect(result).toBe('verbose=true');
+  });
+
+  it('should skip null and undefined values', () => {
+    const result = argsToQueryString({
+      verbose: true,
+      missing: null,
+      absent: undefined,
+    });
+    expect(result).toBe('verbose=true');
+  });
+
+  it('should skip nested objects (non-array)', () => {
+    const result = argsToQueryString({
+      verbose: true,
+      nested: { deep: 'value' },
+    });
+    expect(result).toBe('verbose=true');
+  });
+
+  it('should return empty string for empty args', () => {
+    const result = argsToQueryString({});
+    expect(result).toBe('');
+  });
+
+  it('should return empty string when all keys are internal', () => {
+    const result = argsToQueryString({
+      $0: 'nx',
+      _: [],
+    });
+    expect(result).toBe('');
+  });
+
+  it('should handle numeric values for non-sensitive keys', () => {
+    const result = argsToQueryString({ port: 4200 });
+    expect(result).toBe('port=4200');
+  });
+
+  it('should handle false boolean values', () => {
+    const result = argsToQueryString({ verbose: false });
+    expect(result).toBe('verbose=false');
+  });
+
+  describe('sensitive args sanitization', () => {
+    it('should redact sensitive file paths', () => {
+      const result = argsToQueryString({ file: '/path/to/file.json' });
+      expect(result).toBe('file=%3Credacted%3E');
+    });
+
+    it('should redact sensitive project identifiers', () => {
+      const result = argsToQueryString({
+        project: 'my-secret-app',
+        focus: 'internal-lib',
+      });
+      expect(result).toBe('project=%3Credacted%3E&focus=%3Credacted%3E');
+    });
+
+    it('should preserve boolean values on sensitive keys', () => {
+      const result = argsToQueryString({ runMigrations: true });
+      expect(result).toBe('runMigrations=true');
+    });
+
+    it('should preserve false boolean values on sensitive keys', () => {
+      const result = argsToQueryString({ graph: false });
+      expect(result).toBe('graph=false');
+    });
+
+    it('should redact non-boolean values on sensitive keys', () => {
+      const result = argsToQueryString({
+        runMigrations: 'migrations.json',
+      });
+      expect(result).toBe('runMigrations=%3Credacted%3E');
+    });
+
+    it('should pass through non-sensitive keys unchanged', () => {
+      const result = argsToQueryString({
+        verbose: true,
+        port: 4200,
+        parallel: 3,
+      });
+      expect(result).toBe('verbose=true&port=4200&parallel=3');
+    });
+
+    it('should redact each element of array values for sensitive keys', () => {
+      const result = argsToQueryString({
+        projects: ['secret-app', 'internal-lib'],
+      });
+      expect(result).toBe('projects=%3Credacted%3E&projects=%3Credacted%3E');
+    });
+
+    it('should preserve each element of array values for non-sensitive keys', () => {
+      const result = argsToQueryString({
+        targets: ['build', 'test'],
+      });
+      expect(result).toBe('targets=build&targets=test');
+    });
+
+    it('should catch kebab-case sensitive keys', () => {
+      const result = argsToQueryString({ 'output-path': 'dist/app' });
+      expect(result).toBe('output-path=%3Credacted%3E');
+    });
+
+    it('should handle a real-world graph command scenario', () => {
+      const result = argsToQueryString({
+        file: 'output.json',
+        focus: 'my-secret-app',
+        exclude: 'internal-lib',
+        host: '192.168.1.1',
+        port: 4200,
+        targets: 'build',
+        watch: true,
+      });
+      expect(result).toBe(
+        'file=%3Credacted%3E&focus=%3Credacted%3E&exclude=%3Credacted%3E&host=%3Credacted%3E&port=4200&targets=build&watch=true'
+      );
+    });
+
+    it('should always redact credentials', () => {
+      const result = argsToQueryString({ otp: '123456' });
+      expect(result).toBe('otp=%3Credacted%3E');
+    });
+
+    it('should redact git refs', () => {
+      const result = argsToQueryString({
+        base: 'feature/secret-branch',
+        head: 'main',
+      });
+      expect(result).toBe('base=%3Credacted%3E&head=%3Credacted%3E');
+    });
+
+    it('should redact URLs and hosts', () => {
+      const result = argsToQueryString({
+        baseUrl: 'https://internal.company.com',
+        deployUrl: 'https://staging.company.com/app',
+      });
+      expect(result).toBe('baseUrl=%3Credacted%3E&deployUrl=%3Credacted%3E');
+    });
+
+    it('should handle kebab-case config keys', () => {
+      const result = argsToQueryString({
+        'ts-config': 'tsconfig.app.json',
+        'webpack-config': 'webpack.config.js',
+      });
+      expect(result).toBe(
+        'ts-config=%3Credacted%3E&webpack-config=%3Credacted%3E'
+      );
+    });
+  });
+});