Skip to content

Telemetry

Overview

The telemetry package provides an opt-in framework for collecting pseudonymous usage analytics from CLI tools built on GTB. It is designed around three principles:

  1. Explicit consent. Telemetry is never enabled by default. Users must opt in via telemetry enable, the init prompt, or the TELEMETRY_ENABLED environment variable.
  2. Privacy by design. No personally identifiable information is collected. Machine IDs are derived from multiple system signals and hashed with SHA-256. Command arguments, file contents, and IP addresses are never recorded.
  3. Pluggable backends: tool authors choose where data goes. The framework ships noop, stdout, file, HTTP, and OpenTelemetry (OTLP) backends, and supports custom implementations.

Quick Start

Enable telemetry for your tool

props.Tool{
    Name: "mytool",
    Features: props.SetFeatures(
        props.Enable(props.TelemetryCmd),
    ),
    Telemetry: props.TelemetryConfig{
        Endpoint: "https://analytics.example.com/events",
    },
}

Emit events from commands

func runMyCommand(p *props.Props) error {
    start := time.Now()

    // ... command logic ...

    p.Collector.TrackCommand("my-command", time.Since(start).Milliseconds(), 0, nil)
    return nil
}

User opt-in

mytool telemetry enable    # opt in
mytool telemetry status    # check current state
mytool telemetry disable   # opt out (drops all pending events)
mytool telemetry reset     # clear local data + request remote deletion

In this section

  • What's Collected: Event types, the data collected, and machine identification.
  • Backends: Pluggable backends, selection precedence, delivery modes, and buffering.
  • Configuration: TelemetryConfig, environment variables, and initialiser integration.
  • Privacy & Consent: Two-level gating, GDPR deletion, consent withdrawal, and known limitations.
  • Testing: Testing telemetry collection and backends.