beads/cmd/bd/metrics.go
Matthew 5526d670d8
feat: honor DO_NOT_TRACK as a metrics opt-out (#4938)
* feat: Honor DO_NOT_TRACK as a metrics opt-out

Honor the cross-tool DO_NOT_TRACK standard (https://donottrack.sh/) as an
alias for BD_DISABLE_METRICS. The standard defines a single environment
variable that "clearly and unambiguously expresses a user's wish to opt out
of ... usage reporting, anonymous or not" and instructs authors to "disable
all tracking" when DO_NOT_TRACK is set, alongside existing opt-out mechanisms.

* fix(metrics): make DO_NOT_TRACK a disable-only opt-out

Maintainer review of PR #4938 found DO_NOT_TRACK was wired as a
bidirectional alias of BD_DISABLE_METRICS (`return !envTruthyValue(v)`),
so a falsey or empty value (DO_NOT_TRACK=0/false/"") was treated as a
decisive re-enable that overrode a saved `bd metrics off` — inverting
the stated opt-out intent for values the donottrack.sh standard never
asks tools to treat as opt-in.

Make DO_NOT_TRACK disable-only: only a truthy value opts out; a
falsey/empty value falls through to the user's saved preference.
BD_DISABLE_METRICS stays the higher-precedence bidirectional override.
Keep the `bd metrics` status/on/off override notes consistent by
reporting DO_NOT_TRACK as the effective override only when truthy, so a
falsey DO_NOT_TRACK no longer prints a misleading "overrides your saved
config" note.

Document the disable-only semantics in AGENT_INSTRUCTIONS.md and add
regression tests: falsey/empty DO_NOT_TRACK must not re-enable a saved
metrics-off, BD_DISABLE_METRICS still re-enables bidirectionally, and
the override-reporting helper names the effective var with correct
precedence.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Eddie the Engineer <ci@beads.test>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-21 08:35:20 -07:00

413 lines
16 KiB
Go

package main
import (
"bytes"
"encoding/json"
"fmt"
"os"
"path/filepath"
"runtime"
"sort"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/metrics"
)
// metricsCmd lets users see and control anonymous usage metrics without ever
// hand-editing config or setting an environment variable. `bd metrics on` /
// `bd metrics off` write the user-global config directly and take effect on the
// next command — no shell/supervisor restart required.
var metricsCmd = &cobra.Command{
Use: "metrics",
Short: "Show or change anonymous usage-metrics settings",
Long: `Show whether anonymous usage metrics are on, see exactly what is sent, and
turn them on or off.
bd shares anonymous usage metrics to learn how people actually use it — just
which commands get run, plus the bd version and OS platform. That's how we decide
what to polish next. We never collect your issues, paths, remotes, identity, or
any user-supplied text.
bd metrics show the current status and what is collected
bd metrics on turn metrics on
bd metrics off turn metrics off
bd metrics example show real examples of the events bd sends`,
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
evt := metrics.NewCommandEvent("metrics")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
runMetricsStatus(cmd)
return nil
},
}
var metricsOnCmd = &cobra.Command{
Use: "on",
Short: "Turn anonymous usage metrics on",
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
evt := metrics.NewCommandEvent("metrics-on")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
if err := setMetricsDisabled(false); err != nil {
return HandleError("failed to update metrics setting: %v", err)
}
out := cmd.OutOrStdout()
fmt.Fprintln(out, "✓ Anonymous usage metrics are now ON. Thank you — this genuinely helps us make bd better!")
fmt.Fprintln(out, " See what's sent with `bd metrics example`, or turn it off again with `bd metrics off`.")
warnIfMetricsEnvOverride(cmd, false)
return nil
},
}
var metricsOffCmd = &cobra.Command{
Use: "off",
Short: "Turn anonymous usage metrics off",
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
// Opt-out is intentionally the one command that emits no cli_command
// event. Metrics are still enabled for this invocation (the saved config
// only takes effect next time), so recording a `metrics-off` event would
// queue telemetry the user just declined — and if they re-enable later it
// would flush — directly contradicting the "No usage data will be
// collected or sent" promise printed below. So we write the opt-out and
// add nothing to the collector.
if err := setMetricsDisabled(true); err != nil {
return HandleError("failed to update metrics setting: %v", err)
}
out := cmd.OutOrStdout()
fmt.Fprintln(out, "Anonymous usage metrics are now OFF. No usage data will be collected or sent.")
fmt.Fprintln(out, "Turn them back on anytime with `bd metrics on`. Thanks for giving them a try!")
warnIfMetricsEnvOverride(cmd, true)
return nil
},
}
var metricsExampleCmd = &cobra.Command{
Use: "example",
Short: "Show real examples of the anonymous metrics bd sends",
SilenceUsage: true,
SilenceErrors: true,
RunE: func(cmd *cobra.Command, args []string) error {
evt := metrics.NewCommandEvent("metrics-example")
defer func() {
if c := metrics.Global(); c != nil {
c.CloseEventAndAdd(evt)
}
}()
runMetricsExample(cmd)
return nil
},
}
func init() {
metricsCmd.AddCommand(metricsOnCmd, metricsOffCmd, metricsExampleCmd)
rootCmd.AddCommand(metricsCmd)
}
// setMetricsDisabled writes metrics.disabled to the user-global config. The
// metrics.* prefix routes to the user config automatically, so this is the same
// store the runtime reads — no manual editing and no env var required.
func setMetricsDisabled(disabled bool) error {
val := "false"
if disabled {
val = "true"
}
return config.SetUserYamlConfig("metrics.disabled", val)
}
// metricsEnabledByConfig reports the config-driven state (ignoring the env
// override), which is what `bd metrics on/off` controls. It reads the
// user-global config only — the same store `bd metrics on/off` writes — so a
// project config can never skew the reported "saved" state.
func metricsEnabledByConfig() bool {
return !config.MetricsDisabledByUserConfig()
}
// metricsEnvOverride returns the metrics opt-out env var in effect for this
// shell, if any, preferring BD_DISABLE_METRICS over its DO_NOT_TRACK alias.
// BD_DISABLE_METRICS is a bidirectional override, so it counts whenever it is
// set. DO_NOT_TRACK is disable-only: a falsey or empty DO_NOT_TRACK falls
// through to saved config and overrides nothing, so it is reported as an active
// override only when truthy — matching resolveMetricsEnabled.
func metricsEnvOverride() (name, value string, ok bool) {
if v, found := os.LookupEnv(metrics.EnvDisableMetrics); found {
return metrics.EnvDisableMetrics, v, true
}
if v, found := os.LookupEnv(metrics.EnvDoNotTrack); found && envTruthyValue(v) {
return metrics.EnvDoNotTrack, v, true
}
return "", "", false
}
// warnIfMetricsEnvOverride tells the user when an environment override is set
// and would override the config they just changed, so the toggle never silently
// does nothing.
func warnIfMetricsEnvOverride(cmd *cobra.Command, wantDisabled bool) {
name, v, ok := metricsEnvOverride()
if !ok {
return
}
envDisabled := envTruthyValue(v)
if envDisabled == wantDisabled {
return
}
fmt.Fprintf(cmd.ErrOrStderr(),
"\nNote: %s=%s is set in your environment and overrides this for the current shell.\n"+
" Your config preference is saved; unset %s to let it take effect.\n",
name, v, name)
}
func runMetricsStatus(cmd *cobra.Command) {
out := cmd.OutOrStdout()
effective := resolveMetricsEnabled()
state := "OFF"
if effective {
state = "ON"
}
fmt.Fprintf(out, "Anonymous usage metrics: %s\n\n", state)
fmt.Fprintln(out, "What we collect: the name of each bd command you run, plus the bd version")
fmt.Fprintln(out, "and OS platform, keyed by a machine-derived, HMAC-protected ID. We never")
fmt.Fprintln(out, "collect your issues, paths, remotes, identity, or any text you type. Seeing")
fmt.Fprintln(out, "real usage patterns is how we decide what to improve next — thank you for")
fmt.Fprintln(out, "helping make bd better.")
fmt.Fprintf(out, "\nWhere it goes: %s\n", resolveMetricsEndpoint())
fmt.Fprintln(out, "\n See real examples: bd metrics example")
if effective {
fmt.Fprintln(out, " Turn off: bd metrics off")
} else {
fmt.Fprintln(out, " Turn on: bd metrics on")
}
// Surface the env override if it disagrees with the saved config.
if name, v, ok := metricsEnvOverride(); ok {
if envTruthyValue(v) == metricsEnabledByConfig() {
fmt.Fprintf(cmd.ErrOrStderr(),
"\nNote: %s=%s is overriding your saved config (which is %q) for this shell.\n",
name, v, map[bool]string{true: "on", false: "off"}[metricsEnabledByConfig()])
}
}
}
func runMetricsExample(cmd *cobra.Command) {
out := cmd.OutOrStdout()
fmt.Fprintln(out, "bd sends one kind of anonymous event: a `cli_command` record — one per")
fmt.Fprintln(out, "command you run. Each batch carries a machine-derived, HMAC-protected distinct")
fmt.Fprintln(out, "ID, the bd version, and your OS platform. The only per-event attribute is the")
fmt.Fprintln(out, "command name — never your issues, IDs, paths, remotes, identity, or anything")
fmt.Fprintln(out, "you type. A representative payload:")
fmt.Fprintln(out, "")
example := map[string]any{
"distinct_id": "(machine-derived, HMAC-protected — not your identity)",
"app_name": "beads",
"app_version": Version,
"platform": runtime.GOOS,
"events": []map[string]any{{
"name": "cli_command",
"attributes": []map[string]string{{"key": "command", "value": "ready"}},
}},
}
if b, err := marshalIndentNoEscape(example); err == nil {
fmt.Fprintf(out, " %s\n\n", b)
}
// The most honest "what we send" is the queue itself: show the real events
// currently buffered locally, waiting to be flushed.
shown := showQueuedEvents(out)
if shown == 0 {
fmt.Fprintln(out, "Nothing is queued locally right now. Run a few bd commands (with metrics on)")
fmt.Fprintln(out, "and re-run `bd metrics example` to see the exact payloads buffered on your")
fmt.Fprintln(out, "machine before they are sent.")
}
}
// marshalIndentNoEscape is json.MarshalIndent without Go's default HTML escaping,
// so <, >, and & render as themselves in human-facing example output.
func marshalIndentNoEscape(v any) ([]byte, error) {
var buf bytes.Buffer
enc := json.NewEncoder(&buf)
enc.SetEscapeHTML(false)
enc.SetIndent(" ", " ")
if err := enc.Encode(v); err != nil {
return nil, err
}
return bytes.TrimRight(buf.Bytes(), "\n"), nil
}
// showQueuedEvents pretty-prints the real, locally-buffered event payloads from
// ~/.beads/eventsData (the same files the flusher reads before sending), so the
// user sees exactly what would leave their machine. Returns how many event
// files were shown.
func showQueuedEvents(out interface{ Write([]byte) (int, error) }) int {
dir, err := metrics.DataDir()
if err != nil {
return 0
}
entries, err := os.ReadDir(dir)
if err != nil {
return 0
}
files := make([]string, 0, len(entries))
for _, e := range entries {
if e.IsDir() || strings.HasPrefix(e.Name(), ".") {
continue
}
files = append(files, e.Name())
}
if len(files) == 0 {
return 0
}
sort.Strings(files)
const maxShow = 3
fmt.Fprintf(out, "Currently queued on this machine (%s) — %d batch file(s); showing up to %d:\n\n", dir, len(files), maxShow)
shown := 0
for _, name := range files {
if shown >= maxShow {
break
}
// #nosec G304 -- dir is bd's own metrics data dir and name comes from os.ReadDir of that same dir, not user input
raw, err := os.ReadFile(filepath.Join(dir, name))
if err != nil {
continue
}
var pretty json.RawMessage
if json.Unmarshal(raw, &pretty) != nil {
continue
}
buf, err := marshalIndentNoEscape(pretty)
if err != nil {
continue
}
fmt.Fprintf(out, " %s\n\n", buf)
shown++
}
if len(files) > shown {
fmt.Fprintf(out, " ... and %d more batch file(s).\n", len(files)-shown)
}
return shown
}
// isMetricsCommandContext reports whether cmd is `bd metrics` or one of its
// subcommands — contexts where the first-run notice should not fire because the
// user is already looking at / managing metrics.
func isMetricsCommandContext(cmd *cobra.Command) bool {
return cmd.Name() == "metrics" || (cmd.Parent() != nil && cmd.Parent().Name() == "metrics")
}
// topLevelCommandName returns the name of cmd's top-level ancestor — the command
// directly under the root "bd" command. For `bd hooks run` it returns "hooks";
// for a top-level command it returns that command's own name. This lets context
// checks match a whole command subtree (e.g. all of `bd hooks ...`) by the
// top-level name even when cmd is a nested leaf.
func topLevelCommandName(cmd *cobra.Command) string {
c := cmd
for c.Parent() != nil && c.Parent().Parent() != nil {
c = c.Parent()
}
return c.Name()
}
// firstRunNoticeSuppressedCommands are top-level command names whose contexts are
// machine-facing or hook/protocol bridges, so the friendly first-run metrics
// notice must never write to their stderr (it could corrupt a hook envelope or
// surprise a non-interactive caller). Matched by top-level name so nested
// subcommands like `bd hooks run` are covered too.
var firstRunNoticeSuppressedCommands = map[string]bool{
metrics.SendMetricsSubcommand: true,
"prime": true,
"version": true,
"completion": true,
"__complete": true,
"__completeNoDesc": true,
"hook": true, // bd hook bridge (manages its own store/protocol lifecycle)
"hooks": true, // bd hooks ... (git-hook management/runner)
"codex-hook": true, // codex protocol bridge
"bash": true,
"zsh": true,
"fish": true,
"powershell": true,
}
// firstRunNoticeSuppressedByContext reports whether the current command/output
// context must never emit the friendly first-run metrics notice. This is the
// pure context decision — independent of whether metrics are enabled or the
// notice was already shown — so it stays unit-testable. It suppresses machine
// output (JSON/quiet/hook-json), git-hook execution (BD_GIT_HOOK), the metrics
// command itself, hook/protocol/completion/shell-init commands, the root
// --version/-V probe, and stealth init.
func firstRunNoticeSuppressedByContext(cmd *cobra.Command) bool {
if jsonOutput || quietFlag || primeHookJSONMode {
return true
}
if os.Getenv("BD_GIT_HOOK") == "1" {
return true
}
if isMetricsCommandContext(cmd) {
return true
}
if firstRunNoticeSuppressedCommands[topLevelCommandName(cmd)] {
return true
}
// `bd --version` / `bd -V` is a version probe just like the `version`
// subcommand, so it must not emit (or mark shown) the one-time consent notice.
// The root flag path has top-level command name "bd" and so slips past the
// suppressed-command map above; check the flag directly. GetBool errors for
// commands that do not define a "version" flag, which the err guard ignores.
if v, err := cmd.Flags().GetBool("version"); err == nil && v {
return true
}
// `bd init --stealth` configures invisible per-repository usage; a visible
// consent notice on stderr would contradict that, so suppress it there.
if stealth, err := cmd.Flags().GetBool("stealth"); err == nil && stealth {
return true
}
return false
}
// maybeShowMetricsFirstRunNotice prints a one-time, friendly heads-up the first
// time bd runs with metrics enabled, then records that it was shown so it never
// repeats. It writes to stderr and is suppressed in JSON / hook / protocol /
// quiet / stealth contexts (see firstRunNoticeSuppressedByContext) so it can
// never corrupt machine-readable output.
func maybeShowMetricsFirstRunNotice(cmd *cobra.Command) {
if !resolveMetricsEnabled() {
return
}
// Resolve the "already shown" marker from user-global config only. Reading it
// from merged config would let a repository's .beads/config.yaml set
// metrics.notice_shown: true and suppress this one-time disclosure for a user
// who has never seen it — the same project-override hole closed for consent
// and endpoint resolution.
if config.MetricsNoticeShownByUserConfig() {
return
}
if firstRunNoticeSuppressedByContext(cmd) {
return
}
fmt.Fprintln(os.Stderr, "Thanks for using bd! Quick heads-up: bd shares anonymous usage metrics —")
fmt.Fprintln(os.Stderr, " just which commands get run (plus the bd version and OS platform), never your")
fmt.Fprintln(os.Stderr, " issues, paths, remotes, identity, or anything you type. Seeing how people use")
fmt.Fprintln(os.Stderr, " bd is how we decide what to improve next, so it genuinely makes bd better for")
fmt.Fprintln(os.Stderr, " everyone.")
fmt.Fprintln(os.Stderr, " Curious what's sent? bd metrics example")
fmt.Fprintln(os.Stderr, " Prefer to opt out? bd metrics off (one command, no restart needed)")
fmt.Fprintln(os.Stderr, "")
// Record that the notice was shown so it never repeats. Best-effort: if the
// write fails, we simply may show it again — never block the command.
_ = config.SetUserYamlConfig("metrics.notice_shown", "true")
}