Skip to content

telemetry.md

Latest commit

 

History

History
123 lines (83 loc) · 3.4 KB

telemetry.md

File metadata and controls

123 lines (83 loc) · 3.4 KB
Raw

BackAnt CLI Telemetry

BackAnt CLI includes an opt-in anonymous telemetry system to help us understand how the tool is used and improve it for everyone.

Key Principles

  1. Opt-in by default: Telemetry is disabled until you explicitly consent
  2. Privacy first: We never collect personally identifiable information (PII)
  3. Transparent: You can see exactly what we collect and how to disable it
  4. Non-blocking: Telemetry never slows down or interrupts CLI operations

First-Run Consent

On your first use of BackAnt CLI, you'll be asked:

Help improve BackAnt by sharing anonymous usage data? (y/n)
  • Type y or yes to enable telemetry
  • Type n or no (or press Enter) to disable telemetry
  • Your preference is saved to ~/.backant/config.json

What We Collect

When telemetry is enabled, we collect:

Data Example Purpose
Command names generate api, generate route Understand feature usage
Success/failure status true / false Identify reliability issues
Anonymous device ID a1b2c3d4... (hashed) Count unique users
CLI version 0.7.1 Track version adoption
Session duration 45.2 seconds Understand usage patterns
Platform posix / nt Platform-specific improvements

What We NEVER Collect

  • File paths or project names
  • Usernames, email addresses, or real names
  • IP addresses (PostHog may log these, but we don't use them)
  • Stack traces or error messages
  • Command arguments or options
  • Any file contents or code
  • Environment variables or secrets

How to Disable Telemetry

Option 1: Environment Variable (Recommended)

Set the DO_NOT_TRACK environment variable:

# Bash/Zsh
export DO_NOT_TRACK=1

# Fish
set -x DO_NOT_TRACK 1

# Windows (PowerShell)
$env:DO_NOT_TRACK = "1"

Add this to your shell profile (.bashrc, .zshrc, etc.) to make it permanent.

Option 2: Per-Command Flag

Use the --no-telemetry flag for individual commands:

ant --no-telemetry generate api my-project

Option 3: Reset Configuration

Delete the configuration file to be prompted again:

rm ~/.backant/config.json

Viewing Your Telemetry Settings

Use the --privacy flag to see current telemetry status:

ant --privacy

This displays:

  • Whether telemetry is enabled
  • What data is collected
  • How to change your preferences

Technical Implementation

  • SDK: PostHog Python SDK
  • Batching: Events are batched and sent asynchronously
  • Flush on exit: Remaining events are sent when the CLI exits
  • Silent failures: Network errors are silently ignored (never blocks CLI)
  • No PII validation: All events are sanitized before sending

Data Retention

Telemetry data is stored on PostHog's servers. Please refer to PostHog's privacy policy for their data retention policies.

Configuring PostHog (Self-Hosting)

If you want to use your own PostHog instance:

export BACKANT_POSTHOG_KEY="your-project-api-key"
export BACKANT_POSTHOG_HOST="https://your-posthog-instance.com"

Questions or Concerns

If you have any questions about telemetry or privacy, please:

  1. Open an issue at github.com/backant/backant-cli
  2. Review the source code at ant/utils/telemetry.py

We're committed to being transparent about data collection and respecting your privacy.