The Codegen Project CLI collects anonymous usage data to help us understand how the tool is being used and make data-driven improvements.

We take your privacy seriously. Here's what we collect and what we don't:

• Command usage: Which commands you run (e.g., generate, init)
• Generator types: Which generators you use (e.g., payloads, channels)
• Input source types: Whether you use remote URLs, local relative paths, or absolute paths (not the actual paths)
• Feature usage: Which flags and options you use
• Error categories: Types of errors that occur (not error messages or stack traces)
• System information: CLI version, Node.js version, OS platform
• Execution metrics: Command duration and success rates

• ❌ File paths or file names
• ❌ Actual URLs or file locations
• ❌ File contents or schema details
• ❌ Project names
• ❌ User names or emails
• ❌ API keys or credentials
• ❌ IP addresses (anonymized by analytics provider)
• ❌ Hostnames
• ❌ Environment variable values
• ❌ Git repository information
• ❌ Custom schema structures

View your current telemetry settings:

codegen telemetry status

This shows:

• Whether telemetry is enabled or disabled
• Configuration file location
• What data is collected
• Environment variable overrides

You can disable telemetry in several ways:

codegen telemetry disable

Add to your shell profile (.bashrc, .zshrc, etc.):

export CODEGEN_TELEMETRY_DISABLED=1

Or use the standard DO_NOT_TRACK variable:

export DO_NOT_TRACK=1

CODEGEN_TELEMETRY_DISABLED=1 codegen generate

In your codegen.config.js:

export default {
  inputType: 'asyncapi',
  inputPath: './asyncapi.yaml',
  generators: [/* ... */],
  
  // Disable telemetry for this project
  telemetry: {
    enabled: false
  }
}

codegen telemetry enable

When you run any command for the first time, you'll see a notice about telemetry:

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  The Codegen Project CLI collects anonymous usage data      │
│  to help us improve the tool.                               │
│                                                             │
│  To disable: codegen telemetry disable                      │
│  Learn more: https://the-codegen-project.org/docs/telemetry │
│                                                             │
└─────────────────────────────────────────────────────────────┘

This notice is shown only once. Telemetry is opt-out by default, meaning it's enabled unless you explicitly disable it.

To see what telemetry data is being sent:

CODEGEN_TELEMETRY_DEBUG=1 codegen generate

This logs telemetry events to the console, including:

• The event being tracked
• The telemetry configuration state
• The full payload being sent to the analytics endpoint
• HTTP response status (success/failure)

Events are still sent to the analytics endpoint in debug mode, but you can see exactly what's being transmitted. The events will also appear in GA4 DebugView when debug mode is enabled.

Organizations can point telemetry to their own analytics endpoint using environment variables. These environment variables have the highest priority and will override any configuration from project-level config or global config files:

# Set custom endpoint (highest priority - overrides all other configs)
export CODEGEN_TELEMETRY_ENDPOINT=https://analytics.mycompany.com/telemetry
export CODEGEN_TELEMETRY_ID=custom-tracking-id
export CODEGEN_TELEMETRY_API_SECRET=your-api-secret

Configuration Priority Order (highest to lowest):

1. Environment variables (highest priority):
   • CODEGEN_TELEMETRY_DISABLED / DO_NOT_TRACK - disable telemetry
   • CODEGEN_TELEMETRY_ENDPOINT - custom analytics endpoint
   • CODEGEN_TELEMETRY_ID - custom tracking ID
   • CODEGEN_TELEMETRY_API_SECRET - custom API secret
2. Project-level config (from codegen.config.js)
3. Global config file (~/.the-codegen-project/config.json)

Expected endpoint format (GA4 Measurement Protocol compatible):

POST /telemetry
Content-Type: application/json

{
  "client_id": "anonymous-uuid",
  "events": [{
    "name": "command_executed",
    "params": {
      "command": "generate",
      "flags": "watch",
      "input_source": "local_relative",
      "input_type": "asyncapi",
      "generators": "payloads,parameters",
      "generator_count": 2,
      "duration": 1234,
      "success": true,
      "cli_version": "0.57.0",
      "node_version": "v18.0.0",
      "os": "darwin",
      "ci": false,
      "engagement_time_msec": "1234"
    }
  }]
}

Telemetry settings are stored in:

~/.the-codegen-project/config.json

Example configuration:

{
  "version": "1.0.0",
  "telemetry": {
    "enabled": true,
    "anonymousId": "550e8400-e29b-41d4-a716-446655440000",
    "endpoint": "https://www.google-analytics.com/mp/collect",
    "trackingId": "G-XXXXXXXXXX"
  },
  "hasShownTelemetryNotice": true,
  "lastUpdated": "2024-12-11T10:30:00Z"
}

{
  event: 'command_executed',
  command: 'generate',
  flags: 'watch',                    // Comma-separated if multiple, 'none' if empty
  input_source: 'local_relative',    // Not the actual path!
  input_type: 'asyncapi',
  generators: 'payloads,parameters,channels',  // Comma-separated list
  generator_count: 3,
  duration: 1234,
  success: true,
  cli_version: '0.57.0',
  node_version: 'v18.0.0',
  os: 'darwin',
  ci: false,
  engagement_time_msec: '1234'      // Same as duration for proper engagement tracking
}

Why track generator combinations? This helps us understand:

• Which generators are commonly used together
• Popular generator patterns (e.g., "payloads + parameters")
• If certain generators are always used in isolation
• Common workflows and use cases

{
  event: 'generator_used',
  generator_type: 'payloads',
  input_type: 'asyncapi',          // Can be: asyncapi, openapi, jsonschema
  input_source: 'remote_url',      // Not the actual URL!
  language: 'typescript',
  options: '{"includeValidation":true,"serializationType":"json"}',
  duration: 500,
  success: true,
  cli_version: '0.57.0',
  node_version: 'v18.0.0',
  os: 'darwin',
  ci: false,
  engagement_time_msec: '500'
}

Why track individual generators? This helps us understand:

• Which generators are most popular
• How users configure generators (validation, serialization, etc.)
• Performance characteristics of each generator
• Success/failure rates per generator type

Combined with command_executed event, we get both:

• Macro view: What generators are used together
• Micro view: How each generator is configured

{
  event: 'init_executed',
  config_type: 'esm',
  input_type: 'asyncapi',
  generators: 'payloads,parameters,channels',  // Comma-separated list
  language: 'typescript',
  completed: true,
  cli_version: '0.57.0',
  node_version: 'v18.0.0',
  os: 'darwin',
  ci: false,
  engagement_time_msec: '100'      // Minimum engagement time
}

{
  event: 'error_occurred',
  command: 'generate',
  error_type: 'configuration_error',  // Category only, not actual error message
  cli_version: '0.57.0',
  node_version: 'v18.0.0'
}

Telemetry automatically detects CI environments and adjusts behavior:

• First-run notice is skipped in CI environments
• Telemetry still runs by default (to track CI usage patterns)
• You can disable it with environment variables if needed

Detected CI environments:

• GitHub Actions
• GitLab CI
• CircleCI
• Travis CI
• Jenkins
• Bitbucket Pipelines
• AWS CodeBuild
• TeamCity
• Buildkite

Our telemetry implementation is GDPR compliant:

• ✅ Lawful Basis: Legitimate interest (improving software)
• ✅ Transparency: Clear notice on first run
• ✅ User Control: Easy opt-out mechanism
• ✅ Data Minimization: Only collect necessary data
• ✅ Purpose Limitation: Use only for improvement
• ✅ Anonymization: No PII collected
• ✅ Right to Object: Users can disable anytime

We store data for 14 months, if you use your own telemetry, then its up to you.

Each installation generates a random UUID (v4) as an anonymous identifier. This ID:

• Is NOT tied to your identity
• Cannot be used to identify you personally
• Is only used to understand usage patterns
• Can be reset by deleting the config file

The data we collect helps us:

1. Prioritize features: Focus on the most-used generators and commands
2. Improve reliability: Identify and fix common error scenarios
3. Optimize performance: Understand typical execution times
4. Support platforms: Know which Node.js versions and OS platforms to support
5. Guide documentation: Understand which features cause confusion
6. Understand workflows: Learn whether users prefer remote URLs, relative paths, or absolute paths

• Non-blocking: Telemetry runs asynchronously and never blocks CLI execution
• Fail-safe: Network errors or timeouts don't affect CLI functionality
• Fast timeout: Telemetry requests timeout after 1 second
• Error handling: All errors are handled gracefully and silently

We use Google Analytics 4 Measurement Protocol by default:

• Free service with powerful analytics
• Automatic IP anonymization
• GDPR compliant
• No additional infrastructure needed

In addition to CLI telemetry, our documentation website (https://the-codegen-project.org) also uses Google Analytics 4 to understand how users interact with our documentation.

• Page views: Which documentation pages are viewed
• Navigation: How users navigate through the documentation
• Search queries: What users search for in the docs
• Outbound links: Which external links users click
• Time on page: How long users spend reading documentation
• Referral sources: How users found our documentation

Note: The website uses a different Google Analytics property than the CLI telemetry. They are completely separate tracking systems.

• ❌ Personal information
• ❌ Form inputs or data
• ❌ Clipboard contents
• ❌ Code snippets you copy
• ❌ IP addresses (anonymized by GA4)

Standard Browser Controls:

• Use browser "Do Not Track" settings
• Install privacy extensions (uBlock Origin, Privacy Badger, etc.)
• Use browser incognito/private mode
• Disable JavaScript (documentation still accessible)

Website-Specific Settings:

• Our website respects the DO_NOT_TRACK browser header
• No cookies are set for tracking purposes
• Google Analytics IP anonymization is enabled
• No third-party tracking scripts beyond GA4

A: No. Telemetry runs asynchronously and doesn't block command execution. Network requests timeout after 1 second and fail silently.

A: No. All telemetry functions are designed to never throw errors. Failures are handled internally and don't affect CLI functionality.

A: Yes. Telemetry respects standard HTTP_PROXY and HTTPS_PROXY environment variables. If it fails, it fails silently without affecting the CLI.

A: Yes! Use debug mode:

CODEGEN_TELEMETRY_DEBUG=1 codegen generate

A: Opt-out telemetry provides more representative data about how the tool is actually used, which leads to better improvements for all users. However, we respect your choice to opt-out at any time.

A: Yes! Set CODEGEN_TELEMETRY_ENDPOINT to your internal analytics service. See the "Custom Tracking Endpoint" section above.

A: By default, to Google Analytics 4 (anonymized). You can configure a custom endpoint for organizational tracking.

A: We use an anonymous UUID that is the same across all your projects (any where you interact with the-codegen-project), but it's not tied to any personal information. You can reset it by deleting ~/.the-codegen-project/config.json.

A: No. The CLI uses an anonymous UUID that is never shared with the website. Website analytics use standard Google Analytics browser tracking. There is no way to correlate CLI usage with website visits - they are completely independent systems.

If you have questions or concerns about telemetry:

• GitHub Issues: the-codegen-project/cli