Carbon Telemetry

Carbon Telemetry is a command-line interface tool that collects telemetry data from IBM projects using the Carbon Design System. It automatically tracks package installations and analyzes component usage patterns to help the Carbon team understand adoption patterns and prioritize development efforts.

Package Information

• Package Name: @carbon/telemetry
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install @carbon/telemetry
• Node.js Requirements: v12 or higher

Core Usage

The primary way to use Carbon Telemetry is through the carbon-telemetry CLI command, which is automatically invoked during package installation:

# Automatic collection during package installation
carbon-telemetry collect --install

# Manual component usage analysis
carbon-telemetry collect --components

# Development/testing mode
carbon-telemetry collect --dev @carbon/icons-react

Architecture

Carbon Telemetry is designed as a lightweight, privacy-focused telemetry system:

• Target Scope: Only collects data from IBM projects using Carbon
• Data Collection: Package installation events and component usage patterns
• Local Storage: Uses configstore for persistent configuration and job tracking
• Network Communication: GraphQL API for secure data transmission
• Code Analysis: Babel-based AST parsing for component usage detection
• Error Handling: Silent failures by default, debug mode available via environment variable

Capabilities

CLI Command Interface

The main command interface for executing telemetry collection operations.

/**
 * Carbon Telemetry CLI executable
 * Entry point: carbon-telemetry [command] [options]
 * Requires Node.js v12 or higher
 */

Collect Command

Specifies attributes to be collected from consumer projects. This is the primary command for telemetry data collection.

/**
 * Main collection command for telemetry data
 * Usage: carbon-telemetry collect [options]
 */

Install Collection

Collects package installation and version details when Carbon packages are installed.

# Collect installation data
carbon-telemetry collect --install

Data Collected:

• Package names and versions
• Installation timestamps
• Project context and environment
• Dependency relationships

Component Usage Collection

Analyzes project files to collect component usage details and patterns.

# Collect component usage data
carbon-telemetry collect --components

Data Collected:

• React component import statements
• Component usage frequency
• File-level usage patterns
• JSX element usage tracking

Development Mode

Development and testing mode for package-specific telemetry collection.

# Development mode for specific package
carbon-telemetry collect --dev <package-name>
# Example: carbon-telemetry collect --dev @carbon/react

Global CLI Options

Standard CLI options available for all commands.

# Show version information
carbon-telemetry --version

# Display help information
carbon-telemetry --help

# Show help for collect command
carbon-telemetry collect --help

Environment Configuration

Environment variables for controlling telemetry behavior.

/**
 * Environment Variables:
 * - CARBON_TELEMETRY_DEBUG: Enable debug mode for error reporting and logging
 * - CARBON_TELEMETRY_DISABLED: Set to "1" to disable all telemetry collection
 * - CARBON_TELEMETRY_ENDPOINT: Override default GraphQL endpoint URL
 */

Environment Variable Usage:

# Enable debug mode
CARBON_TELEMETRY_DEBUG=1 carbon-telemetry collect --install

# Disable telemetry collection
CARBON_TELEMETRY_DISABLED=1 carbon-telemetry collect --install

# Use custom endpoint
CARBON_TELEMETRY_ENDPOINT=https://custom.endpoint.com carbon-telemetry collect --install

Integration Patterns

Automatic Installation Tracking

Carbon Telemetry is typically integrated into Carbon packages via postinstall scripts:

{
  "scripts": {
    "postinstall": "carbon-telemetry collect --install"
  }
}

Used in Carbon packages:

• @carbon/react
• @carbon/components
• @carbon/icons-react
• @carbon/pictograms-react
• @carbon/carbon-react

Project File Analysis

For component usage analysis, the tool automatically:

1. Discovers JavaScript/TypeScript files in the project
2. Parses files using Babel AST parser
3. Identifies React component imports from Carbon packages
4. Tracks JSX element usage patterns
5. Reports aggregated usage statistics

Data Privacy and Scope

Privacy Safeguards:

• Data collection is restricted to IBM projects only
• No sensitive source code is transmitted
• Only structural usage patterns are collected
• Local configuration prevents duplicate collection
• Can be completely disabled via CARBON_TELEMETRY_DISABLED=1

IBM Project Detection: The tool includes mechanisms to verify that data collection only occurs within IBM project environments.

Error Handling

Silent Failure Mode (Default)

By default, telemetry collection fails silently to avoid disrupting package installation:

// Errors are caught and suppressed unless debug mode is enabled
try {
  // Telemetry collection logic
} catch (error) {
  if (process.env.CARBON_TELEMETRY_DEBUG) {
    throw error;
  }
  // Silent failure - installation continues normally
}

Debug Mode

Enable detailed error reporting and logging:

CARBON_TELEMETRY_DEBUG=1 carbon-telemetry collect --install

Debug mode provides:

• Detailed error messages and stack traces
• Network request/response logging
• File analysis progress information
• Configuration and environment details

Technical Implementation

Code Analysis Engine

Uses Babel parser and traverse for JavaScript/TypeScript analysis:

/**
 * File Analysis Capabilities:
 * - JavaScript and TypeScript parsing
 * - React component import detection
 * - JSX element usage tracking
 * - AST-based code analysis
 */

Network Communication

GraphQL-based API communication for data submission:

/**
 * GraphQL Mutations:
 * - PackageInstall: Reports package installation events
 * - CollectFileDetails: Submits file analysis data
 */

Configuration Management

Persistent local configuration using configstore:

/**
 * Configuration Features:
 * - Job tracking to prevent duplicate collection
 * - Local storage for collection state
 * - Cross-platform configuration directory
 */

Build and Distribution

The package is distributed as a pre-bundled executable:

• Source: Built from src/cli.js using esbuild
• Bundle: Single cli.js file (~6.1MB) with all dependencies
• Target: Node.js v12+ compatibility (validated at runtime)
• Platform: Cross-platform Node.js executable
• Key Dependencies: @babel/parser, @babel/traverse, configstore, got, yargs

/**
 * Runtime Node.js Version Check:
 * - Validates Node.js version >= 12 on startup
 * - Exits gracefully with status 0 if version requirement not met
 * - Only logs version error when CARBON_TELEMETRY_DEBUG is set
 */