feat(telemetry): adding initial telemetry functionality to the cli

[billxinli]

Summary

This PR adds telemetry functionality to the Socket CLI to track usage patterns, performance metrics, and errors. The implementation includes instrumentation across CLI commands, subprocess executions, and API interactions.

Telemetry Infrastructure

• Organization-scoped tracking: All telemetry requires org context - cannot track without organization
• Event batching: Configurable batch sizes with periodic flushing (500ms intervals)
• Graceful degradation: Telemetry failures never block CLI execution
• Session tracking: Unique session IDs per CLI invocation
• Privacy-first: Comprehensive PII sanitization (tokens, file paths, package names)
• Queue size limiting: Max 1,000 events to prevent memory leaks during API outages
• Timeout protection: 2-second max flush time prevents hanging on exit

Event Types Tracked

• CLI lifecycle: cli_start, cli_complete, cli_error
• Subprocess execution: subprocess_start, subprocess_complete, subprocess_error
• API interactions: api_request, api_response, api_error
• Custom events: Generic event tracking with metadata support

PII Sanitization

• API tokens: Redacts sktsec_* tokens and hex tokens
• File paths: Replaces home directory with ~
• Package names: Strips package arguments after wrapper CLIs
• Sensitive flags: Redacts values after --api-token, --token, -t

Example Sanitization

Input:  ['node', 'socket', 'npm', 'install', '@my/private-pkg', '--token', 'sktsec_abc123']
Output: ['npm', 'install']  // Package name and token removed

Telemetry Configuration

  const TELEMETRY_SERVICE_CONFIG = {
    batch_size: 10,           // Events per batch
    flush_interval: 500,      // 0.5 second periodic flush
    flush_timeout: 2_000,     // 2 second max flush duration
    max_queue_size: 1_000,    // Memory leak protection
  }

Breaking Changes

None. Telemetry is opt-in via organization configuration and fails gracefully.

Example Run:

SOCKET_CLI_API_BASE_URL=http://localhost:8866/v0/ SOCKET_CLI_DEBUG=1 DEBUG=* node dist/cli.js orgs list

---

Note

Add org-scoped telemetry across CLI lifecycle, subprocess wrappers, and SDK HTTP hooks with robust exit handling, sanitization, and comprehensive tests.

• Telemetry Infrastructure:
  • Add org-scoped telemetry service in src/utils/telemetry/* with batching, flush (async/sync), session IDs, and timeouts.
  • Add sanitization of argv and error data; skip telemetry in test env.
  • Register exit handlers (beforeExit, SIGINT/SIGTERM/SIGHUP) via setupTelemetryExitHandlers().
• CLI Integration (src/cli.mts):
  • Track cli_start, cli_complete, cli_error; handle fatal errors (uncaughtException, unhandledRejection) and finalize telemetry before exit.
• Subprocess Wrappers (src/commands/*/cmd-*.mts):
  • Track subprocess_start and subprocess_* on exit for npm, npx, pnpm, yarn; flush telemetry before process exit.
• SDK Hooks (src/utils/sdk.mts):
  • Add request/response hooks to emit api_request, api_response, api_error (skipping /telemetry endpoints) and keep debug logs.
• Ecosystem Utilities (src/utils/ecosystem.mts):
  • Expand ALL_ECOSYSTEMS (e.g., alpm, qpkg, vscode) and relax a type check due to version mismatch.
• Tests:
  • Add unit tests for CLI telemetry, SDK hooks, telemetry integration, and service (src/test/*.mts, src/utils/**/*test.mts).
• Dependencies:
  • Bump @socketsecurity/sdk to 1.4.95; update lockfile.

^{Written by Cursor Bugbot for commit 36ee7fa. Configure here.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​socketsecurity/​sdk@​1.4.94 ⏵ 1.4.95

View full report

[cursor]

Comment @cursor review or bugbot run to trigger another review on this PR

[billxinli]

@cursor review

[cursor]

Comment @cursor review or bugbot run to trigger another review on this PR

[socket-security-staging]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​socketsecurity/​sdk@​1.4.94 ⏵ 1.4.95

View full report