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>
This commit is contained in:
parent
2a63eb3182
commit
5526d670d8
6 changed files with 262 additions and 8 deletions
|
|
@ -503,7 +503,12 @@ collected. Events are written under `~/.beads/eventsData` and POSTed to
|
|||
Metrics are enabled by default (opt-out). The friendliest way to see or change
|
||||
them is `bd metrics` (`bd metrics on` / `bd metrics off` / `bd metrics example`),
|
||||
which takes effect on the next command with no restart. `BD_DISABLE_METRICS=1`
|
||||
still works as a one-off, shell-scoped override.
|
||||
still works as a one-off, shell-scoped override. The cross-tool
|
||||
[`DO_NOT_TRACK`](https://donottrack.sh/) standard is honored as a disable-only
|
||||
opt-out: `DO_NOT_TRACK=1` opts out, while a falsey or empty value
|
||||
(`DO_NOT_TRACK=0`, `false`, or unset-but-present) falls through to your saved
|
||||
`bd metrics` preference instead of forcing metrics back on. `BD_DISABLE_METRICS`
|
||||
is the bidirectional override and takes precedence when both are set.
|
||||
|
||||
## Questions?
|
||||
|
||||
|
|
|
|||
|
|
@ -86,7 +86,7 @@ func metricsTestEnv(home string, extra ...string) []string {
|
|||
base := bdEnv(home)
|
||||
out := make([]string, 0, len(base)+len(extra)+1)
|
||||
for _, e := range base {
|
||||
if strings.HasPrefix(e, "BD_DISABLE_METRICS=") {
|
||||
if strings.HasPrefix(e, "BD_DISABLE_METRICS=") || strings.HasPrefix(e, "DO_NOT_TRACK=") {
|
||||
continue
|
||||
}
|
||||
out = append(out, e)
|
||||
|
|
|
|||
|
|
@ -1699,6 +1699,14 @@ func resolveMetricsEnabled() bool {
|
|||
if v, ok := os.LookupEnv(metrics.EnvDisableMetrics); ok {
|
||||
return !envTruthyValue(v)
|
||||
}
|
||||
// DO_NOT_TRACK is a disable-only alias: a truthy value opts out, but a
|
||||
// falsey or empty value (DO_NOT_TRACK=0/false/"") must fall through to the
|
||||
// user's saved preference instead of forcing metrics back on over a saved
|
||||
// `bd metrics off`. Only BD_DISABLE_METRICS (checked first) is a
|
||||
// bidirectional override.
|
||||
if v, ok := os.LookupEnv(metrics.EnvDoNotTrack); ok && envTruthyValue(v) {
|
||||
return false
|
||||
}
|
||||
// Consent is the user's own global choice: resolve it from the user-global
|
||||
// config only, never merged project/BEADS_DIR config. Otherwise a
|
||||
// repository's .beads/config.yaml (highest viper precedence) could re-enable
|
||||
|
|
|
|||
|
|
@ -137,11 +137,27 @@ func metricsEnabledByConfig() bool {
|
|||
return !config.MetricsDisabledByUserConfig()
|
||||
}
|
||||
|
||||
// warnIfMetricsEnvOverride tells the user when BD_DISABLE_METRICS is set and
|
||||
// would override the config they just changed, so the toggle never silently
|
||||
// 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) {
|
||||
v, ok := os.LookupEnv(metrics.EnvDisableMetrics)
|
||||
name, v, ok := metricsEnvOverride()
|
||||
if !ok {
|
||||
return
|
||||
}
|
||||
|
|
@ -152,7 +168,7 @@ func warnIfMetricsEnvOverride(cmd *cobra.Command, wantDisabled bool) {
|
|||
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",
|
||||
metrics.EnvDisableMetrics, v, metrics.EnvDisableMetrics)
|
||||
name, v, name)
|
||||
}
|
||||
|
||||
func runMetricsStatus(cmd *cobra.Command) {
|
||||
|
|
@ -177,11 +193,11 @@ func runMetricsStatus(cmd *cobra.Command) {
|
|||
}
|
||||
|
||||
// Surface the env override if it disagrees with the saved config.
|
||||
if v, ok := os.LookupEnv(metrics.EnvDisableMetrics); ok {
|
||||
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",
|
||||
metrics.EnvDisableMetrics, v, map[bool]string{true: "on", false: "off"}[metricsEnabledByConfig()])
|
||||
name, v, map[bool]string{true: "on", false: "off"}[metricsEnabledByConfig()])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@ import (
|
|||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/steveyegge/beads/internal/config"
|
||||
"github.com/steveyegge/beads/internal/metrics"
|
||||
)
|
||||
|
||||
// TestMetricsOnOffWritesUserConfig verifies `bd metrics on/off` persists the
|
||||
|
|
@ -282,3 +283,226 @@ func TestFirstRunNoticeSuppressedByContext(t *testing.T) {
|
|||
}
|
||||
})
|
||||
}
|
||||
|
||||
// TestResolveMetricsEnabledHonorsDoNotTrack verifies the cross-tool DO_NOT_TRACK
|
||||
// standard (https://donottrack.sh/) is honored as a disable-only opt-out: a
|
||||
// truthy DO_NOT_TRACK opts out, a falsey or empty DO_NOT_TRACK falls through to
|
||||
// the (here default-enabled) config rather than force-enabling, and
|
||||
// BD_DISABLE_METRICS takes precedence when both are set. The guard that a falsey
|
||||
// DO_NOT_TRACK must not re-enable a saved `bd metrics off` lives in
|
||||
// TestResolveMetricsDoNotTrackIsDisableOnly.
|
||||
func TestResolveMetricsEnabledHonorsDoNotTrack(t *testing.T) {
|
||||
home := t.TempDir()
|
||||
t.Setenv("HOME", home)
|
||||
t.Setenv("USERPROFILE", home)
|
||||
t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
|
||||
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
|
||||
|
||||
for _, key := range []string{metrics.EnvDisableMetrics, metrics.EnvDoNotTrack} {
|
||||
if orig, ok := os.LookupEnv(key); ok {
|
||||
_ = os.Unsetenv(key)
|
||||
t.Cleanup(func() { _ = os.Setenv(key, orig) })
|
||||
}
|
||||
}
|
||||
|
||||
config.ResetForTesting()
|
||||
t.Cleanup(config.ResetForTesting)
|
||||
if err := config.Initialize(); err != nil {
|
||||
t.Fatalf("config.Initialize: %v", err)
|
||||
}
|
||||
if !metricsEnabledByConfig() {
|
||||
t.Fatalf("precondition: metrics should be enabled by default config")
|
||||
}
|
||||
|
||||
cases := []struct {
|
||||
name string
|
||||
disableEnv *string
|
||||
doNotTrack *string
|
||||
wantEnabled bool
|
||||
}{
|
||||
{name: "no env uses config default", wantEnabled: true},
|
||||
{name: "DO_NOT_TRACK=1 disables", doNotTrack: strPtr("1"), wantEnabled: false},
|
||||
{name: "DO_NOT_TRACK=true disables", doNotTrack: strPtr("true"), wantEnabled: false},
|
||||
{name: "DO_NOT_TRACK=0 falls through to config (enabled here)", doNotTrack: strPtr("0"), wantEnabled: true},
|
||||
{name: "DO_NOT_TRACK empty falls through to config (enabled here)", doNotTrack: strPtr(""), wantEnabled: true},
|
||||
{name: "BD_DISABLE_METRICS=0 wins over DO_NOT_TRACK=1", disableEnv: strPtr("0"), doNotTrack: strPtr("1"), wantEnabled: true},
|
||||
{name: "BD_DISABLE_METRICS=1 wins over DO_NOT_TRACK=0", disableEnv: strPtr("1"), doNotTrack: strPtr("0"), wantEnabled: false},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
if tc.disableEnv != nil {
|
||||
t.Setenv(metrics.EnvDisableMetrics, *tc.disableEnv)
|
||||
}
|
||||
if tc.doNotTrack != nil {
|
||||
t.Setenv(metrics.EnvDoNotTrack, *tc.doNotTrack)
|
||||
}
|
||||
if got := resolveMetricsEnabled(); got != tc.wantEnabled {
|
||||
t.Errorf("resolveMetricsEnabled() = %v, want %v", got, tc.wantEnabled)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestResolveMetricsDoNotTrackIsDisableOnly is the regression guard for the
|
||||
// PR #4938 review finding that a falsey DO_NOT_TRACK could re-enable telemetry
|
||||
// over an explicit opt-out. With a saved `bd metrics off`, DO_NOT_TRACK=0,
|
||||
// false, or empty must fall through to that saved-off preference and never turn
|
||||
// metrics back on. BD_DISABLE_METRICS stays a bidirectional override that can
|
||||
// re-enable.
|
||||
func TestResolveMetricsDoNotTrackIsDisableOnly(t *testing.T) {
|
||||
home := t.TempDir()
|
||||
t.Setenv("HOME", home)
|
||||
t.Setenv("USERPROFILE", home)
|
||||
t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
|
||||
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
|
||||
|
||||
for _, key := range []string{metrics.EnvDisableMetrics, metrics.EnvDoNotTrack} {
|
||||
if orig, ok := os.LookupEnv(key); ok {
|
||||
_ = os.Unsetenv(key)
|
||||
t.Cleanup(func() { _ = os.Setenv(key, orig) })
|
||||
}
|
||||
}
|
||||
|
||||
// Persist `bd metrics off` to the user-global config before initializing.
|
||||
userCfgDir := filepath.Join(home, ".config", "bd")
|
||||
if err := os.MkdirAll(userCfgDir, 0o755); err != nil {
|
||||
t.Fatalf("mkdir user config dir: %v", err)
|
||||
}
|
||||
if err := os.WriteFile(filepath.Join(userCfgDir, "config.yaml"),
|
||||
[]byte("metrics:\n disabled: true\n"), 0o600); err != nil {
|
||||
t.Fatalf("write user config: %v", err)
|
||||
}
|
||||
|
||||
config.ResetForTesting()
|
||||
t.Cleanup(config.ResetForTesting)
|
||||
if err := config.Initialize(); err != nil {
|
||||
t.Fatalf("config.Initialize: %v", err)
|
||||
}
|
||||
if metricsEnabledByConfig() {
|
||||
t.Fatalf("precondition: saved config should be metrics-off")
|
||||
}
|
||||
|
||||
cases := []struct {
|
||||
name string
|
||||
disableEnv *string
|
||||
doNotTrack *string
|
||||
wantEnabled bool
|
||||
}{
|
||||
{name: "saved-off, no env stays off", wantEnabled: false},
|
||||
{name: "DO_NOT_TRACK=0 does not re-enable saved-off", doNotTrack: strPtr("0"), wantEnabled: false},
|
||||
{name: "DO_NOT_TRACK=false does not re-enable saved-off", doNotTrack: strPtr("false"), wantEnabled: false},
|
||||
{name: "DO_NOT_TRACK empty does not re-enable saved-off", doNotTrack: strPtr(""), wantEnabled: false},
|
||||
{name: "DO_NOT_TRACK=1 keeps saved-off disabled", doNotTrack: strPtr("1"), wantEnabled: false},
|
||||
{name: "BD_DISABLE_METRICS=0 re-enables saved-off (bidirectional)", disableEnv: strPtr("0"), wantEnabled: true},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
if tc.disableEnv != nil {
|
||||
t.Setenv(metrics.EnvDisableMetrics, *tc.disableEnv)
|
||||
}
|
||||
if tc.doNotTrack != nil {
|
||||
t.Setenv(metrics.EnvDoNotTrack, *tc.doNotTrack)
|
||||
}
|
||||
if got := resolveMetricsEnabled(); got != tc.wantEnabled {
|
||||
t.Errorf("resolveMetricsEnabled() = %v, want %v", got, tc.wantEnabled)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestMetricsEnvOverrideReporting locks the env-override reporting contract that
|
||||
// backs the `bd metrics` status/on/off notes: BD_DISABLE_METRICS is preferred
|
||||
// when both are set, a truthy DO_NOT_TRACK is named as the effective override,
|
||||
// and a disable-only falsey DO_NOT_TRACK is not reported as an override at all
|
||||
// (it overrides nothing, so a note would be misleading).
|
||||
func TestMetricsEnvOverrideReporting(t *testing.T) {
|
||||
for _, key := range []string{metrics.EnvDisableMetrics, metrics.EnvDoNotTrack} {
|
||||
if orig, ok := os.LookupEnv(key); ok {
|
||||
_ = os.Unsetenv(key)
|
||||
t.Cleanup(func() { _ = os.Setenv(key, orig) })
|
||||
}
|
||||
}
|
||||
|
||||
cases := []struct {
|
||||
name string
|
||||
disableEnv *string
|
||||
doNotTrack *string
|
||||
wantName string // "" means no override should be reported
|
||||
}{
|
||||
{name: "no env reports nothing", wantName: ""},
|
||||
{name: "DO_NOT_TRACK=1 is reported", doNotTrack: strPtr("1"), wantName: metrics.EnvDoNotTrack},
|
||||
{name: "DO_NOT_TRACK=0 is not reported", doNotTrack: strPtr("0"), wantName: ""},
|
||||
{name: "DO_NOT_TRACK empty is not reported", doNotTrack: strPtr(""), wantName: ""},
|
||||
{name: "BD_DISABLE_METRICS preferred over DO_NOT_TRACK", disableEnv: strPtr("1"), doNotTrack: strPtr("1"), wantName: metrics.EnvDisableMetrics},
|
||||
{name: "BD_DISABLE_METRICS=0 is reported (bidirectional)", disableEnv: strPtr("0"), wantName: metrics.EnvDisableMetrics},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
if tc.disableEnv != nil {
|
||||
t.Setenv(metrics.EnvDisableMetrics, *tc.disableEnv)
|
||||
}
|
||||
if tc.doNotTrack != nil {
|
||||
t.Setenv(metrics.EnvDoNotTrack, *tc.doNotTrack)
|
||||
}
|
||||
name, _, ok := metricsEnvOverride()
|
||||
if tc.wantName == "" {
|
||||
if ok {
|
||||
t.Errorf("metricsEnvOverride() reported %q, want no override", name)
|
||||
}
|
||||
return
|
||||
}
|
||||
if !ok || name != tc.wantName {
|
||||
t.Errorf("metricsEnvOverride() = (%q, ok=%v), want name %q", name, ok, tc.wantName)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestWarnIfMetricsEnvOverrideNamesActiveVar verifies the toggle warning names
|
||||
// the actually-effective override variable dynamically (regression guard for the
|
||||
// helper refactor that replaced a hard-coded BD_DISABLE_METRICS string), and
|
||||
// that a disable-only falsey DO_NOT_TRACK produces no warning.
|
||||
func TestWarnIfMetricsEnvOverrideNamesActiveVar(t *testing.T) {
|
||||
for _, key := range []string{metrics.EnvDisableMetrics, metrics.EnvDoNotTrack} {
|
||||
if orig, ok := os.LookupEnv(key); ok {
|
||||
_ = os.Unsetenv(key)
|
||||
t.Cleanup(func() { _ = os.Setenv(key, orig) })
|
||||
}
|
||||
}
|
||||
|
||||
// The user is turning metrics on, so a truthy disable env disagrees and warns.
|
||||
warn := func() string {
|
||||
var buf bytes.Buffer
|
||||
cmd := &cobra.Command{}
|
||||
cmd.SetOut(&buf)
|
||||
cmd.SetErr(&buf)
|
||||
warnIfMetricsEnvOverride(cmd, false)
|
||||
return buf.String()
|
||||
}
|
||||
|
||||
t.Run("names DO_NOT_TRACK when it is the override", func(t *testing.T) {
|
||||
t.Setenv(metrics.EnvDoNotTrack, "1")
|
||||
got := warn()
|
||||
if !strings.Contains(got, "DO_NOT_TRACK") {
|
||||
t.Errorf("warning = %q, want it to name DO_NOT_TRACK", got)
|
||||
}
|
||||
if strings.Contains(got, "BD_DISABLE_METRICS") {
|
||||
t.Errorf("warning = %q, should not name BD_DISABLE_METRICS when only DO_NOT_TRACK is set", got)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("prefers BD_DISABLE_METRICS when both set", func(t *testing.T) {
|
||||
t.Setenv(metrics.EnvDisableMetrics, "1")
|
||||
t.Setenv(metrics.EnvDoNotTrack, "1")
|
||||
if got := warn(); !strings.Contains(got, "BD_DISABLE_METRICS") {
|
||||
t.Errorf("warning = %q, want it to name BD_DISABLE_METRICS", got)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("falsey DO_NOT_TRACK does not warn", func(t *testing.T) {
|
||||
t.Setenv(metrics.EnvDoNotTrack, "0")
|
||||
if got := warn(); got != "" {
|
||||
t.Errorf("warning = %q, want no warning for disable-only falsey DO_NOT_TRACK", got)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ const (
|
|||
|
||||
EnvDisableMetrics = "BD_DISABLE_METRICS"
|
||||
EnvDisableEventFlush = "BD_DISABLE_EVENT_FLUSH"
|
||||
EnvDoNotTrack = "DO_NOT_TRACK"
|
||||
|
||||
DefaultEndpoint = "https://gastownhall-eventsapi.com/mp/collect"
|
||||
)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue