telemetry

Documentation

Overview

Package telemetry implements anonymous usage telemetry for the bitwave CLI.

Design constraints, in order:

• Nothing sensitive ever leaves the machine: command paths and flag NAMES only — never argument values, payees, amounts, accounts, file paths, or addresses.
• Zero latency cost: events append to a local spool; the spool flushes in batches after a command's real work finishes, with a hard timeout. Telemetry can never slow down or fail a command.
• Non-interactive first: disclosure is a one-time stderr notice, never a prompt. Opt out with `bitwave telemetry disable`, BITWAVE_TELEMETRY=0, or the cross-tool DO_NOT_TRACK=1 convention.

The wire contract (POST {endpoint} with {"events": [...]}) is documented in docs/TELEMETRY.md.

Index

• func AnonymousIdForStatus() string
• func Endpoint() string
• func MaybeFlush(version string, force bool)
• func NoticeIfNeeded(version string, quiet bool)
• func RecordCommand(version string, c *cobra.Command, runErr error, duration time.Duration)
• func SetDisabled(disabled bool)
• func SpoolCount() int
• type Decision
  • func Decide(version string) Decision
• type Event

Functions

func AnonymousIdForStatus

func AnonymousIdForStatus() string

AnonymousIdForStatus exposes the id for `telemetry status` without creating one as a side effect.

func Endpoint

func Endpoint() string

Endpoint returns the ingest URL (override: BITWAVE_TELEMETRY_URL).

func MaybeFlush

func MaybeFlush(version string, force bool)

MaybeFlush sends the spool to the ingest endpoint when it is due (enough events, or the oldest is stale). Runs after a command's work is complete; silent on every failure. Set force to flush regardless of thresholds.

func NoticeIfNeeded

func NoticeIfNeeded(version string, quiet bool)

NoticeIfNeeded prints the one-time disclosure to stderr and marks it shown. Never a prompt: this is disclosure for humans and agent transcripts alike. Suppressed (and left pending) under quiet mode so it surfaces on a later non-quiet run.

func RecordCommand

func RecordCommand(version string, c *cobra.Command, runErr error, duration time.Duration)

RecordCommand appends one event to the spool. Safe to call with a nil command (nothing recorded). All errors are swallowed.

func SetDisabled

func SetDisabled(disabled bool)

SetDisabled persists the user's choice; disabling also wipes the spool so nothing recorded earlier can be sent later.

func SpoolCount

func SpoolCount() int

SpoolCount reports how many events are waiting locally.

Types

type Decision

type Decision struct {
	Enabled bool
	Reason  string // "BITWAVE_TELEMETRY env", "DO_NOT_TRACK env", "disabled via `bitwave telemetry disable`", "default (enabled)", "dev build"
}

Decision explains whether telemetry is on and why — surfaced by `bitwave telemetry status`.

func Decide

func Decide(version string) Decision

Decide resolves the opt-out precedence: explicit env > dev-build guard > DO_NOT_TRACK > persisted choice > default-on. Dev/snapshot builds never send by default, but an explicit BITWAVE_TELEMETRY=1 overrides (useful to exercise the pipeline before a release).

type Event

type Event struct {
	Schema         string   `json:"schema"`
	Ts             string   `json:"ts"`
	AnonymousId    string   `json:"anonymousId"`
	Version        string   `json:"version"`
	Os             string   `json:"os"`
	Arch           string   `json:"arch"`
	InstallChannel string   `json:"installChannel"`
	Command        string   `json:"command"`
	Flags          []string `json:"flags,omitempty"`
	DurationMs     int64    `json:"durationMs"`
	Ok             bool     `json:"ok"`
	ErrorClass     string   `json:"errorClass,omitempty"`
	AgentTokenEnv  bool     `json:"agentTokenEnv"`
	Tty            bool     `json:"tty"`
	Harness        string   `json:"harness,omitempty"`
}

Event is one CLI invocation. Field names are the wire format.