diff --git a/cmd/bd/command_telemetry.go b/cmd/bd/command_telemetry.go new file mode 100644 index 000000000..a97834926 --- /dev/null +++ b/cmd/bd/command_telemetry.go @@ -0,0 +1,71 @@ +package main + +import ( + "context" + + "go.opentelemetry.io/otel/attribute" + oteltrace "go.opentelemetry.io/otel/trace" + + "github.com/steveyegge/beads/internal/debug" + "github.com/steveyegge/beads/internal/telemetry" +) + +// commandSpanAttrs builds the initial attribute set for the bd.command. +// span. Pulled out so tests can assert the attribute set without touching +// global OTel state. The bd.actor attribute is stamped later via SetAttributes +// in main.go once getActorWithGit() resolves. +// +// secretFlags names the flag tokens whose values must never reach the +// bd.args attribute (see secretFlagTokens); scrubArgsForTelemetry also +// applies its DSN/userinfo scrub to every arg, so a nil map still redacts +// positional connection strings. +func commandSpanAttrs(cmdName, version string, args []string, secretFlags map[string]bool) []attribute.KeyValue { + return []attribute.KeyValue{ + attribute.String("bd.command", cmdName), + attribute.String("bd.version", version), + attribute.String("bd.args", scrubArgsForTelemetry(args, secretFlags)), + } +} + +// initTelemetry initializes OTel providers for this invocation. +// +// Telemetry init failures are non-fatal — they are logged via debug and +// telemetry falls back to noop providers, matching the rest of bd's +// "telemetry is opt-in, never blocks the user" stance. +// +// Extracted so the call from main.go's PreRunE is a single testable line. +// Must run before any DB access so SQL spans nest under the command span; +// in main.go it runs ahead of the usage-metrics bootstrap block (a separate +// subsystem, unrelated to OTel), so it is kept independent of +// startCommandSpan rather than folded into a single combined call. +func initTelemetry(ctx context.Context, version string) { + if err := telemetry.Init(ctx, "bd", version); err != nil { + debug.Logf("warning: telemetry init failed: %v", err) + } +} + +// startCommandSpan starts the root bd.command. span. Returns the new +// context (carrying the span) and the span itself for End(). +// +// Assumes initTelemetry has already run for this invocation; does not call +// telemetry.Init itself so callers can gate the usage-metrics bootstrap +// block (e.g. skipping span creation for the internal send-metrics +// subcommand) between the two. +func startCommandSpan(ctx context.Context, cmdName, version string, args []string, secretFlags map[string]bool) (context.Context, oteltrace.Span) { + return telemetry.Tracer("bd").Start(ctx, "bd.command."+cmdName, + oteltrace.WithAttributes(commandSpanAttrs(cmdName, version, args, secretFlags)...), + ) +} + +// startCommandTelemetry composes initTelemetry + startCommandSpan into a +// single call for callers that don't need to interleave other setup between +// the two steps (e.g. tests exercising the combined wiring contract). +// +// The original PR-3475 bug (telemetry.WrapStorage implemented but never +// called) taught us that wiring inside cobra PreRunE is exactly the kind of +// code that decays silently — this and its two constituent halves exist so +// that wiring is a single testable line wherever it's used. +func startCommandTelemetry(ctx context.Context, cmdName, version string, args []string, secretFlags map[string]bool) (context.Context, oteltrace.Span) { + initTelemetry(ctx, version) + return startCommandSpan(ctx, cmdName, version, args, secretFlags) +} diff --git a/cmd/bd/command_telemetry_test.go b/cmd/bd/command_telemetry_test.go new file mode 100644 index 000000000..189a2f61e --- /dev/null +++ b/cmd/bd/command_telemetry_test.go @@ -0,0 +1,84 @@ +package main + +import ( + "context" + "os" + "testing" +) + +// clearTelemetryEnv unsets every BD_OTEL_* / OTEL_* variable telemetry.Enabled +// or the SDK looks at, using t.Setenv so the harness restores them on test +// exit. Local to cmd/bd because a sibling helper in internal/telemetry would +// be in a different package; this duplication keeps cmd/bd's tests hermetic +// without exporting a test-only helper. +func clearTelemetryEnv(t *testing.T) { + t.Helper() + for _, k := range []string{ + "BD_OTEL_ENABLED", + "BD_OTEL_METRICS_URL", + "BD_OTEL_LOGS_URL", + "BD_OTEL_STDOUT", + "OTEL_SDK_DISABLED", + "OTEL_SERVICE_NAME", + "OTEL_RESOURCE_ATTRIBUTES", + "OTEL_EXPORTER_OTLP_ENDPOINT", + "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", + "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", + "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT", + "OTEL_TRACES_EXPORTER", + "OTEL_METRICS_EXPORTER", + } { + t.Setenv(k, "") + _ = os.Unsetenv(k) + } +} + +func TestCommandSpanAttrs(t *testing.T) { + got := commandSpanAttrs("ready", "1.0.4-dev", []string{"--json", "--include-deferred"}, nil) + + want := map[string]string{ + "bd.command": "ready", + "bd.version": "1.0.4-dev", + "bd.args": "--json --include-deferred", + } + if len(got) != len(want) { + t.Fatalf("commandSpanAttrs returned %d attrs; want %d", len(got), len(want)) + } + for _, kv := range got { + expected, ok := want[string(kv.Key)] + if !ok { + t.Errorf("unexpected attribute %q in span attrs", kv.Key) + continue + } + if kv.Value.AsString() != expected { + t.Errorf("attr %q = %q; want %q", kv.Key, kv.Value.AsString(), expected) + } + } +} + +func TestCommandSpanAttrs_EmptyArgs(t *testing.T) { + got := commandSpanAttrs("status", "v1", nil, nil) + for _, kv := range got { + if string(kv.Key) == "bd.args" && kv.Value.AsString() != "" { + t.Errorf("bd.args with nil args = %q; want empty string", kv.Value.AsString()) + } + } +} + +// startCommandTelemetry composes Init + Tracer.Start. The bd.command. +// span is the parent for every storage and AI span downstream — silently +// returning nil here would break trace nesting across the whole invocation. +// Whether the span actually records is governed by telemetry.Init (covered +// in internal/telemetry/telemetry_test.go); this test guards the wiring +// contract: the function must always return a non-nil context and span. +func TestStartCommandTelemetry_DisabledStillReturnsSpan(t *testing.T) { + clearTelemetryEnv(t) + ctx, span := startCommandTelemetry(context.Background(), "ready", "1.0.0", []string{"--json"}, nil) + if ctx == nil { + t.Fatal("startCommandTelemetry returned nil context") + } + if span == nil { + t.Fatal("startCommandTelemetry returned nil span") + } + span.End() +} diff --git a/cmd/bd/main.go b/cmd/bd/main.go index 30bd85335..e8275faf6 100644 --- a/cmd/bd/main.go +++ b/cmd/bd/main.go @@ -881,11 +881,11 @@ var rootCmd = &cobra.Command{ // per-command context and losing Ctrl-C entirely. setRootContext(setupGracefulShutdown()) - // Initialize OTel (no-op unless BD_OTEL_METRICS_URL or BD_OTEL_STDOUT=true). - // Must run before any DB access so SQL spans nest under command spans. - if err := telemetry.Init(rootCtx, "bd", Version); err != nil { - debug.Logf("warning: telemetry init failed: %v", err) - } + // Initialize OTel. Telemetry is opt-in — initTelemetry is a noop + // unless BD_OTEL_ENABLED=true or a legacy BD_OTEL_* selector is set. + // Must run before any DB access so SQL spans nest under the command + // span. + initTelemetry(rootCtx, Version) // Materialize the user-level metrics config only when metrics are // actually enabled. When metrics are disabled (BD_DISABLE_METRICS or a @@ -911,13 +911,7 @@ var rootCmd = &cobra.Command{ // Start root span for this command. rootCtx now carries the span, so // all downstream DB and AI calls become child spans automatically. - rootCtx, commandSpan = telemetry.Tracer("bd").Start(rootCtx, "bd.command."+cmd.Name(), - oteltrace.WithAttributes( - attribute.String("bd.command", cmd.Name()), - attribute.String("bd.version", Version), - attribute.String("bd.args", scrubArgsForTelemetry(os.Args[1:], secretFlagTokens(cmd))), - ), - ) + rootCtx, commandSpan = startCommandSpan(rootCtx, cmd.Name(), Version, os.Args[1:], secretFlagTokens(cmd)) // Apply verbosity flags early (before any output) debug.SetVerbose(verboseFlag) diff --git a/cmd/bd/storage_chain_test.go b/cmd/bd/storage_chain_test.go index 9ecb0dfa0..08cf4f130 100644 --- a/cmd/bd/storage_chain_test.go +++ b/cmd/bd/storage_chain_test.go @@ -2,7 +2,6 @@ package main import ( "context" - "os" "testing" "github.com/steveyegge/beads/internal/hooks" @@ -23,19 +22,10 @@ func (s *stubChainStore) ActiveDatabaseSize(context.Context) (int64, error) { return s.databaseSize, nil } -// clearTelemetryEnv unsets every BD_OTEL_* variable telemetry.Enabled -// inspects, so each test starts from a known baseline. -func clearTelemetryEnv(t *testing.T) { - t.Helper() - for _, k := range []string{ - "BD_OTEL_METRICS_URL", - "BD_OTEL_LOGS_URL", - "BD_OTEL_STDOUT", - } { - t.Setenv(k, "") - _ = os.Unsetenv(k) - } -} +// clearTelemetryEnv is defined once for the package, in +// command_telemetry_test.go; it unsets every BD_OTEL_* / OTEL_* variable +// telemetry.Enabled or the SDK looks at, so each test starts from a known +// baseline. func TestWireStorageDecorators_NilStorePassesThrough(t *testing.T) { if got := wireStorageDecorators(nil, hooks.NewRunner("/nonexistent"), false); got != nil { diff --git a/docs/reference/observability.md b/docs/reference/observability.md index 68a2b9d1e..cfbf210a1 100644 --- a/docs/reference/observability.md +++ b/docs/reference/observability.md @@ -20,13 +20,18 @@ docker compose up -d ## Configuration -One variable is enough. Add it to your shell profile or workspace `.env`: +Telemetry is **explicit opt-in**. Set `BD_OTEL_ENABLED=true` and configure the +exporter via standard OpenTelemetry SDK environment variables — both go in +your shell profile or workspace `.env`: ```bash -export BD_OTEL_METRICS_URL=http://localhost:8428/opentelemetry/api/v1/push +export BD_OTEL_ENABLED=true +export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:8428/opentelemetry/api/v1/push ``` -Every `bd` command will then automatically push its metrics. +A standard `OTEL_*` variable alone will not turn bd telemetry on — `bd` won't +auto-activate from a machine-global `OTEL_*` setting that was set for some +other instrumented tool. Log export is not implemented yet. `BD_OTEL_LOGS_URL` is reserved for a future VictoriaLogs exporter and does not activate telemetry today. @@ -35,33 +40,66 @@ VictoriaLogs exporter and does not activate telemetry today. ```bash # ~/.zshrc or ~/.bashrc -export BD_OTEL_METRICS_URL=http://localhost:8428/opentelemetry/api/v1/push +export BD_OTEL_ENABLED=true +export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:8428/opentelemetry/api/v1/push ``` ### Environment variables | Variable | Example | Description | |----------|---------|-------------| -| `BD_OTEL_METRICS_URL` | `http://localhost:8428/opentelemetry/api/v1/push` | Push metrics to VictoriaMetrics. Activates telemetry. | -| `BD_OTEL_LOGS_URL` | `http://localhost:9428/insert/opentelemetry/v1/logs` | Reserved for future log export. Does not activate telemetry today. | -| `BD_OTEL_STDOUT` | `true` | Write spans and metrics to stderr (dev/debug). Also activates telemetry. | +| `BD_OTEL_ENABLED` | `true` | **Master switch.** Activates telemetry. Without it, the variables below are ignored. | +| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | `http://localhost:8428/opentelemetry/api/v1/push` | Push metrics to an OTLP HTTP receiver. | +| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | `http://localhost:9428/insert/opentelemetry/v1/logs` | Push logs to an OTLP HTTP receiver (reserved for future log export). | +| `OTEL_TRACES_EXPORTER` | `console` | Write spans to stderr (dev/debug). | +| `OTEL_METRICS_EXPORTER` | `console` | Metric exporter selection, comma-separated (`otlp`, `console`, `none`). Unset defaults to `otlp`; `console` writes to stderr (dev/debug); a selection without `otlp` never exports to an OTLP endpoint, even if one is configured machine-globally. | +| `OTEL_SERVICE_NAME` | `bd` | Override the `service.name` resource attribute. | +| `OTEL_RESOURCE_ATTRIBUTES` | `deployment.environment=workstation,team=infra` | Extend or override resource attributes (comma-separated `key=value`). | +| `OTEL_SDK_DISABLED` | `true` | Force telemetry off even when `BD_OTEL_ENABLED=true` is set. | + +### Resource attributes + +Every metric and span carries the OTel resource describing the bd process: + +| Attribute | Value | Notes | +|-----------|-------|-------| +| `service.name` | `bd` | Override with `OTEL_SERVICE_NAME`. | +| `service.version` | bd version | | + +Add anything else via `OTEL_RESOURCE_ATTRIBUTES`. ### Local debug mode ```bash -BD_OTEL_STDOUT=true bd list +BD_OTEL_ENABLED=true OTEL_TRACES_EXPORTER=console OTEL_METRICS_EXPORTER=console bd list ``` +### Legacy environment variables (deprecated) + +The earlier `BD_OTEL_*` data variables are honored for backwards +compatibility. Setting any of them activates telemetry on its own (no +`BD_OTEL_ENABLED=true` required) and translates to the standard OTLP equivalent +— a legacy value wins over a pre-existing `OTEL_*` value so a machine-global +`OTEL_*` setting cannot silently redirect bd telemetry. Each `bd` invocation +that sees one logs a one-line deprecation warning to stderr: + +| Legacy | Standard equivalent | +|--------|---------------------| +| `BD_OTEL_METRICS_URL` | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | +| `BD_OTEL_LOGS_URL` | `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | +| `BD_OTEL_STDOUT=true` | `OTEL_TRACES_EXPORTER=console` + `OTEL_METRICS_EXPORTER=console` | + ## Verification ```bash bd list # triggers metrics → visible in VictoriaMetrics ``` -Verification query in Grafana (VictoriaMetrics datasource): +Verification queries in Grafana (VictoriaMetrics datasource): ```promql -bd_storage_operations_total +bd_storage_operations_total # raw counter +sum(rate(bd_storage_operations_total[5m])) # operation rate ``` ### Confirm storage instrumentation locally @@ -120,7 +158,7 @@ present, the storage decorator is not in the chain — check ## Traces (spans) -Spans are only exported when `BD_OTEL_STDOUT=true` — there is no trace backend in the recommended local stack. +Spans are only exported when `OTEL_TRACES_EXPORTER=console` — there is no trace backend in the recommended local stack. | Span | Source | Description | |------|--------|-------------| @@ -162,8 +200,9 @@ The `hook.stdout` / `hook.stderr` events carry two attributes: `output` (the tex ``` cmd/bd/main.go └─ telemetry.Init() - ├─ BD_OTEL_STDOUT=true → TracerProvider stdout + MeterProvider stdout - └─ BD_OTEL_METRICS_URL → MeterProvider HTTP → VictoriaMetrics + ├─ OTEL_TRACES_EXPORTER=console → TracerProvider stdout + ├─ OTEL_METRICS_EXPORTER=console → MeterProvider stdout + └─ OTEL_EXPORTER_OTLP_METRICS_ENDPOINT → MeterProvider HTTP → VictoriaMetrics internal/storage/dolt/ → bd_db_* metrics + dolt.* spans internal/storage/ephemeral/ → ephemeral.* spans @@ -173,5 +212,6 @@ internal/compact/ → bd_ai_* metrics + anthropic.* spans internal/telemetry/storage.go → bd_storage_* metrics (SDK wrapper) ``` -When neither variable is set, `telemetry.Init()` installs **no-op** providers: -hot paths execute only no-op calls with no memory allocation. +When no OpenTelemetry SDK environment variable selects an exporter, +`telemetry.Init()` installs **no-op** providers: hot paths execute only no-op +calls with no memory allocation. diff --git a/internal/telemetry/otlp.go b/internal/telemetry/otlp.go deleted file mode 100644 index b11d4ea60..000000000 --- a/internal/telemetry/otlp.go +++ /dev/null @@ -1,15 +0,0 @@ -package telemetry - -import ( - "context" - - "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp" - sdkmetric "go.opentelemetry.io/otel/sdk/metric" -) - -// buildOTLPMetricExporter creates an HTTP/protobuf OTLP metric exporter. -// url is a full HTTP URL, e.g. http://localhost:8428/opentelemetry/api/v1/push -// (VictoriaMetrics format). Compatible with any OTLP HTTP metric receiver. -func buildOTLPMetricExporter(ctx context.Context, url string) (sdkmetric.Exporter, error) { - return otlpmetrichttp.New(ctx, otlpmetrichttp.WithEndpointURL(url)) -} diff --git a/internal/telemetry/telemetry.go b/internal/telemetry/telemetry.go index 46d6db38c..d1f5ae505 100644 --- a/internal/telemetry/telemetry.go +++ b/internal/telemetry/telemetry.go @@ -1,20 +1,50 @@ // Package telemetry provides OpenTelemetry integration for beads. // -// Telemetry is opt-in: set BD_OTEL_METRICS_URL or BD_OTEL_STDOUT=true to activate. -// No overhead when neither variable is set. +// Telemetry is explicit opt-in: nothing is exported unless BD_OTEL_ENABLED=true +// (or a legacy BD_OTEL_* variable) is set. No overhead when off — bd will not +// auto-activate from a machine-global OTEL_* variable that was set for some +// other instrumented tool. // // # Configuration // -// BD_OTEL_METRICS_URL=http://localhost:8428/opentelemetry/api/v1/push -// Push metrics to VictoriaMetrics (or any OTLP HTTP receiver). -// Presence of this variable enables telemetry. +// BD_OTEL_ENABLED=true +// Master switch. Activates telemetry; without it the standard OTEL_* +// variables below are ignored. // -// BD_OTEL_LOGS_URL=http://localhost:9428/insert/opentelemetry/v1/logs -// Reserved for future log export to VictoriaLogs. +// Once activated, beads honors the standard OpenTelemetry SDK environment +// variables: // -// BD_OTEL_STDOUT=true -// Write spans and metrics to stderr (dev/debug mode). -// Also activates telemetry when set alone. +// OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:8428/opentelemetry/api/v1/push +// Push metrics to an OTLP HTTP receiver (e.g. VictoriaMetrics). +// +// OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:9428/insert/opentelemetry/v1/logs +// Push logs to an OTLP HTTP receiver (reserved for future log export). +// +// OTEL_TRACES_EXPORTER=console +// OTEL_METRICS_EXPORTER=console +// Write spans / metrics to stderr (dev/debug mode). +// OTEL_METRICS_EXPORTER is a comma-separated selection (otlp, console, +// none); unset defaults to otlp per the SDK spec, and the OTLP metric +// exporter is installed only when the selection includes otlp AND an +// OTLP endpoint is configured. +// +// OTEL_SERVICE_NAME=bd +// OTEL_RESOURCE_ATTRIBUTES=key=value,... +// Override or extend resource attributes (service.name, service.version, +// deployment.environment, ...). +// +// OTEL_SDK_DISABLED=true +// Force telemetry off even when BD_OTEL_ENABLED=true is set. +// +// # Legacy environment variables +// +// The earlier BD_OTEL_* variables remain honored for backwards compatibility +// and take precedence over their OTEL_* equivalents. A deprecation warning is +// logged when any are detected: +// +// BD_OTEL_METRICS_URL → OTEL_EXPORTER_OTLP_METRICS_ENDPOINT +// BD_OTEL_LOGS_URL → OTEL_EXPORTER_OTLP_LOGS_ENDPOINT +// BD_OTEL_STDOUT=true → OTEL_TRACES_EXPORTER=console + OTEL_METRICS_EXPORTER=console // // # Recommended local stack // @@ -29,9 +59,11 @@ import ( "context" "fmt" "os" + "strings" "time" "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp" "go.opentelemetry.io/otel/exporters/stdout/stdoutmetric" "go.opentelemetry.io/otel/exporters/stdout/stdouttrace" "go.opentelemetry.io/otel/metric" @@ -49,39 +81,98 @@ const instrumentationScope = "github.com/steveyegge/beads" var shutdownFns []func(context.Context) error // Enabled reports whether telemetry is active. -// True when BD_OTEL_METRICS_URL is set or BD_OTEL_STDOUT=true. +// +// Active when explicitly opted in (BD_OTEL_ENABLED=true) or when a legacy +// BD_OTEL_* variable is set, and not disabled via OTEL_SDK_DISABLED=true. +// Standard OTEL_* variables on their own do not activate telemetry — they +// configure it once an opt-in is in effect, so a machine-global OTEL_* setting +// for some other instrumented tool can't silently turn bd telemetry on. func Enabled() bool { - return os.Getenv("BD_OTEL_METRICS_URL") != "" || - os.Getenv("BD_OTEL_STDOUT") == "true" + if strings.EqualFold(os.Getenv("OTEL_SDK_DISABLED"), "true") { + return false + } + return strings.EqualFold(os.Getenv("BD_OTEL_ENABLED"), "true") || hasLegacySelector() } -// Init configures OTel providers. -// When neither BD_OTEL_METRICS_URL nor BD_OTEL_STDOUT is set, installs no-op -// providers and returns immediately (zero overhead path). -// -// Traces are exported only when BD_OTEL_STDOUT=true (stdout, for local debugging). -// Metrics are exported to BD_OTEL_METRICS_URL and/or stdout. -func Init(ctx context.Context, serviceName, version string) error { - if !Enabled() { - otel.SetTracerProvider(tracenoop.NewTracerProvider()) - otel.SetMeterProvider(metricnoop.NewMeterProvider()) - return nil - } +func hasLegacySelector() bool { + return os.Getenv("BD_OTEL_METRICS_URL") != "" || + os.Getenv("BD_OTEL_LOGS_URL") != "" || + strings.EqualFold(os.Getenv("BD_OTEL_STDOUT"), "true") +} - res, err := resource.New(ctx, +// translateLegacyEnv copies any BD_OTEL_* environment variable into its +// standard OTEL_* equivalent, unconditionally — a legacy value wins over a +// pre-existing standard value so an unrelated machine-global OTEL_* setting +// cannot silently redirect bd telemetry. Returns one human-readable mapping +// string for each legacy variable found. +func translateLegacyEnv() []string { + var mappings []string + if u := os.Getenv("BD_OTEL_METRICS_URL"); u != "" { + _ = os.Setenv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", u) + mappings = append(mappings, "BD_OTEL_METRICS_URL → OTEL_EXPORTER_OTLP_METRICS_ENDPOINT") + } + if u := os.Getenv("BD_OTEL_LOGS_URL"); u != "" { + _ = os.Setenv("OTEL_EXPORTER_OTLP_LOGS_ENDPOINT", u) + mappings = append(mappings, "BD_OTEL_LOGS_URL → OTEL_EXPORTER_OTLP_LOGS_ENDPOINT") + } + if strings.EqualFold(os.Getenv("BD_OTEL_STDOUT"), "true") { + _ = os.Setenv("OTEL_TRACES_EXPORTER", "console") + // Keep the OTLP destination when the legacy metrics URL is also set; + // otherwise BD_OTEL_STDOUT means console-only and must not let a + // machine-global OTLP endpoint pull in a remote exporter. + metricsSel := "console" + if os.Getenv("BD_OTEL_METRICS_URL") != "" { + metricsSel = "console,otlp" + } + _ = os.Setenv("OTEL_METRICS_EXPORTER", metricsSel) + mappings = append(mappings, "BD_OTEL_STDOUT=true → OTEL_TRACES_EXPORTER=console + OTEL_METRICS_EXPORTER="+metricsSel) + } + return mappings +} + +// buildResource assembles the OTel Resource describing this bd process. +// +// Defaults are merged with the host/process detectors and finally with the +// FromEnv detector, so OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES can +// override anything set by the caller. +func buildResource(ctx context.Context, serviceName, version string) (*resource.Resource, error) { + return resource.New(ctx, resource.WithAttributes( semconv.ServiceNameKey.String(serviceName), semconv.ServiceVersionKey.String(version), ), resource.WithHost(), resource.WithProcess(), + resource.WithFromEnv(), ) +} + +// Init configures OTel providers. +// When no opt-in is in effect (BD_OTEL_ENABLED=true or any legacy BD_OTEL_* +// selector), installs no-op providers and returns immediately (zero overhead). +// +// Traces are exported only when OTEL_TRACES_EXPORTER=console (stdout, for +// local debugging); there is no remote trace backend. +// Metrics are exported to OTEL_EXPORTER_OTLP_METRICS_ENDPOINT and/or stdout. +func Init(ctx context.Context, serviceName, version string) error { + if mappings := translateLegacyEnv(); len(mappings) > 0 { + fmt.Fprintf(os.Stderr, + "warning: BD_OTEL_* environment variables are deprecated. Replace with BD_OTEL_ENABLED=true plus the standard OpenTelemetry SDK variables. Translated for this run: %s\n", + strings.Join(mappings, "; ")) + } + + if !Enabled() { + otel.SetTracerProvider(tracenoop.NewTracerProvider()) + otel.SetMeterProvider(metricnoop.NewMeterProvider()) + return nil + } + + res, err := buildResource(ctx, serviceName, version) if err != nil { return fmt.Errorf("telemetry: resource: %w", err) } - // Traces: stdout only (local debug). No remote trace backend in the default stack. - if os.Getenv("BD_OTEL_STDOUT") == "true" { + if strings.EqualFold(os.Getenv("OTEL_TRACES_EXPORTER"), "console") { tp, err := buildTraceProvider(ctx, res) if err != nil { return fmt.Errorf("telemetry: trace provider: %w", err) @@ -92,7 +183,6 @@ func Init(ctx context.Context, serviceName, version string) error { otel.SetTracerProvider(tracenoop.NewTracerProvider()) } - // Metrics: VictoriaMetrics (HTTP) and/or stdout. mp, err := buildMetricProvider(ctx, res) if err != nil { return fmt.Errorf("telemetry: metric provider: %w", err) @@ -118,7 +208,9 @@ func buildTraceProvider(_ context.Context, res *resource.Resource) (*sdktrace.Tr func buildMetricProvider(ctx context.Context, res *resource.Resource) (*sdkmetric.MeterProvider, error) { opts := []sdkmetric.Option{sdkmetric.WithResource(res)} - if os.Getenv("BD_OTEL_STDOUT") == "true" { + console, otlp := selectedMetricExporters() + + if console { exp, err := stdoutmetric.New() if err != nil { return nil, err @@ -128,8 +220,8 @@ func buildMetricProvider(ctx context.Context, res *resource.Resource) (*sdkmetri )) } - if url := os.Getenv("BD_OTEL_METRICS_URL"); url != "" { - exp, err := buildOTLPMetricExporter(ctx, url) + if otlp && otlpMetricsEndpointSet() { + exp, err := otlpmetrichttp.New(ctx) if err != nil { return nil, fmt.Errorf("otlp metric exporter: %w", err) } @@ -141,6 +233,35 @@ func buildMetricProvider(ctx context.Context, res *resource.Resource) (*sdkmetri return sdkmetric.NewMeterProvider(opts...), nil } +// selectedMetricExporters parses OTEL_METRICS_EXPORTER as the comma-separated +// exporter list the OTel SDK spec defines. Unset means "otlp" (the SDK +// default); "none" disables metric export entirely. Gating the OTLP reader on +// the selector — not just on an endpoint being present — is what keeps a +// console-only selection (e.g. legacy BD_OTEL_STDOUT=true) from exporting to +// a machine-global OTEL_EXPORTER_OTLP_ENDPOINT set for some other tool. +func selectedMetricExporters() (console, otlp bool) { + sel := os.Getenv("OTEL_METRICS_EXPORTER") + if strings.TrimSpace(sel) == "" { + return false, true + } + for _, tok := range strings.Split(sel, ",") { + switch strings.ToLower(strings.TrimSpace(tok)) { + case "console": + console = true + case "otlp": + otlp = true + case "none": + return false, false + } + } + return console, otlp +} + +func otlpMetricsEndpointSet() bool { + return os.Getenv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT") != "" || + os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT") != "" +} + // Tracer returns a tracer with the given instrumentation name (or the global scope). func Tracer(name string) trace.Tracer { if name == "" { diff --git a/internal/telemetry/telemetry_test.go b/internal/telemetry/telemetry_test.go new file mode 100644 index 000000000..3beeb8e4a --- /dev/null +++ b/internal/telemetry/telemetry_test.go @@ -0,0 +1,373 @@ +package telemetry + +import ( + "context" + "io" + "os" + "strings" + "testing" + "time" + + "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/attribute" + metricnoop "go.opentelemetry.io/otel/metric/noop" + tracenoop "go.opentelemetry.io/otel/trace/noop" +) + +// clearAllEnv clears every BD_OTEL_* and OTEL_* env var the package looks at, +// using t.Setenv so the harness restores them on test exit. +func clearAllEnv(t *testing.T) { + t.Helper() + for _, k := range []string{ + "BD_OTEL_ENABLED", + "BD_OTEL_METRICS_URL", + "BD_OTEL_LOGS_URL", + "BD_OTEL_STDOUT", + "OTEL_SDK_DISABLED", + "OTEL_SERVICE_NAME", + "OTEL_RESOURCE_ATTRIBUTES", + "OTEL_EXPORTER_OTLP_ENDPOINT", + "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", + "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", + "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT", + "OTEL_TRACES_EXPORTER", + "OTEL_METRICS_EXPORTER", + } { + t.Setenv(k, "") + _ = os.Unsetenv(k) + } +} + +func TestTranslateLegacyEnv_NoLegacyVars(t *testing.T) { + clearAllEnv(t) + mappings := translateLegacyEnv() + if len(mappings) != 0 { + t.Fatalf("expected no mappings when no legacy vars set, got %v", mappings) + } +} + +func TestTranslateLegacyEnv_MetricsURL(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_METRICS_URL", "http://example.com/metrics") + mappings := translateLegacyEnv() + if got := os.Getenv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"); got != "http://example.com/metrics" { + t.Errorf("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT = %q, want %q", got, "http://example.com/metrics") + } + if !containsSubstr(mappings, "BD_OTEL_METRICS_URL") { + t.Errorf("mappings should mention BD_OTEL_METRICS_URL, got %v", mappings) + } +} + +func TestTranslateLegacyEnv_LegacyOverridesStandard(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_METRICS_URL", "http://legacy.example/metrics") + t.Setenv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", "http://standard.example/metrics") + translateLegacyEnv() + // Backwards-compat: BD_OTEL_* must win unconditionally so an existing + // machine-global OTEL_* setting can't silently redirect bd telemetry. + if got := os.Getenv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"); got != "http://legacy.example/metrics" { + t.Errorf("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT = %q, want legacy value to win", got) + } +} + +func TestTranslateLegacyEnv_LogsURL(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_LOGS_URL", "http://example.com/logs") + translateLegacyEnv() + if got := os.Getenv("OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"); got != "http://example.com/logs" { + t.Errorf("OTEL_EXPORTER_OTLP_LOGS_ENDPOINT = %q, want %q", got, "http://example.com/logs") + } +} + +func TestTranslateLegacyEnv_Stdout(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_STDOUT", "true") + translateLegacyEnv() + if got := os.Getenv("OTEL_TRACES_EXPORTER"); got != "console" { + t.Errorf("OTEL_TRACES_EXPORTER = %q, want console", got) + } + if got := os.Getenv("OTEL_METRICS_EXPORTER"); got != "console" { + t.Errorf("OTEL_METRICS_EXPORTER = %q, want console", got) + } +} + +func TestTranslateLegacyEnv_StdoutPlusMetricsURLKeepsOTLP(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_STDOUT", "true") + t.Setenv("BD_OTEL_METRICS_URL", "http://example.invalid/metrics") + translateLegacyEnv() + if got := os.Getenv("OTEL_METRICS_EXPORTER"); got != "console,otlp" { + t.Errorf("OTEL_METRICS_EXPORTER = %q, want console,otlp", got) + } +} + +func TestSelectedMetricExporters(t *testing.T) { + cases := []struct { + sel string + console, otlp bool + }{ + {"", false, true}, // SDK default + {"otlp", false, true}, + {"console", true, false}, + {"console,otlp", true, true}, + {" Console , OTLP ", true, true}, + {"none", false, false}, + {"console,none", false, false}, // none wins + {"bogus", false, false}, + } + for _, c := range cases { + clearAllEnv(t) + t.Setenv("OTEL_METRICS_EXPORTER", c.sel) + console, otlp := selectedMetricExporters() + if console != c.console || otlp != c.otlp { + t.Errorf("selectedMetricExporters(%q) = console:%v otlp:%v, want console:%v otlp:%v", + c.sel, console, otlp, c.console, c.otlp) + } + } +} + +// A console-only selection (the BD_OTEL_STDOUT=true translation) must not let +// a machine-global OTLP endpoint install a remote exporter — the scenario the +// legacy-wins guarantee in the package docs promises against. +func TestSelectedMetricExporters_ConsoleOnlyIgnoresGlobalEndpoint(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_STDOUT", "true") + t.Setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://example.invalid:4318") + translateLegacyEnv() + _, otlp := selectedMetricExporters() + if otlp { + t.Error("console-only selection still enables OTLP exporter with a machine-global endpoint set") + } +} + +func TestEnabled_NoVarsSet(t *testing.T) { + clearAllEnv(t) + if Enabled() { + t.Error("Enabled() should be false when no OTel env vars set") + } +} + +func TestEnabled_LegacyMetricsURL(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_METRICS_URL", "http://example.com/metrics") + if !Enabled() { + t.Error("Enabled() should be true when BD_OTEL_METRICS_URL set") + } +} + +func TestEnabled_LegacyStdout(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_STDOUT", "true") + if !Enabled() { + t.Error("Enabled() should be true when BD_OTEL_STDOUT=true") + } +} + +func TestEnabled_BDOTELEnabledTrue(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_ENABLED", "true") + if !Enabled() { + t.Error("Enabled() should be true when BD_OTEL_ENABLED=true") + } +} + +func TestEnabled_StandardEndpointAloneDoesNotActivate(t *testing.T) { + // A machine-global OTEL_* setting (e.g. for some other instrumented tool) + // must not silently turn bd telemetry on — explicit opt-in is required. + clearAllEnv(t) + t.Setenv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", "http://example.com/metrics") + if Enabled() { + t.Error("Enabled() should be false when only OTEL_* set without BD_OTEL_ENABLED") + } +} + +func TestEnabled_StandardEndpointWithBDOTELEnabled(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_ENABLED", "true") + t.Setenv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", "http://example.com/metrics") + if !Enabled() { + t.Error("Enabled() should be true when both BD_OTEL_ENABLED and OTEL_* set") + } +} + +func TestEnabled_SDKDisabledOverridesEverything(t *testing.T) { + clearAllEnv(t) + t.Setenv("BD_OTEL_ENABLED", "true") + t.Setenv("BD_OTEL_METRICS_URL", "http://example.com/metrics") + t.Setenv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT", "http://example.com/metrics") + t.Setenv("OTEL_SDK_DISABLED", "true") + if Enabled() { + t.Error("Enabled() should be false when OTEL_SDK_DISABLED=true, even if other vars set") + } +} + +func TestBuildResource_DefaultServiceName(t *testing.T) { + clearAllEnv(t) + res, err := buildResource(context.Background(), "bd", "1.0.0") + if err != nil { + t.Fatalf("buildResource: %v", err) + } + got, ok := lookupAttr(res.Attributes(), "service.name") + if !ok { + t.Fatal("service.name missing") + } + if got.AsString() != "bd" { + t.Errorf("service.name = %q, want bd", got.AsString()) + } +} + +func TestBuildResource_OTELServiceNameOverridesDefault(t *testing.T) { + clearAllEnv(t) + t.Setenv("OTEL_SERVICE_NAME", "bd-assistant") + res, err := buildResource(context.Background(), "bd", "1.0.0") + if err != nil { + t.Fatalf("buildResource: %v", err) + } + got, ok := lookupAttr(res.Attributes(), "service.name") + if !ok { + t.Fatal("service.name missing") + } + if got.AsString() != "bd-assistant" { + t.Errorf("service.name = %q, want bd-assistant (env should override default)", got.AsString()) + } +} + +func TestBuildResource_OTELResourceAttributesMerged(t *testing.T) { + clearAllEnv(t) + t.Setenv("OTEL_RESOURCE_ATTRIBUTES", "deployment.environment=workstation,team=infra") + res, err := buildResource(context.Background(), "bd", "1.0.0") + if err != nil { + t.Fatalf("buildResource: %v", err) + } + got, ok := lookupAttr(res.Attributes(), "deployment.environment") + if !ok { + t.Fatal("deployment.environment missing — WithFromEnv should pick it up") + } + if got.AsString() != "workstation" { + t.Errorf("deployment.environment = %q, want workstation", got.AsString()) + } + got, ok = lookupAttr(res.Attributes(), "team") + if !ok { + t.Fatal("team missing") + } + if got.AsString() != "infra" { + t.Errorf("team = %q, want infra", got.AsString()) + } +} + +// resetTelemetryState restores noop providers and clears registered shutdown +// hooks after a test that called Init, so global OTel state doesn't leak +// between tests. +func resetTelemetryState(t *testing.T) { + t.Helper() + t.Cleanup(func() { + // Bound the flush: tests configure unreachable endpoints + // (example.invalid), and an unbounded Shutdown lets OTLP retry for + // ~30s before the test can finish. + ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second) + defer cancel() + Shutdown(ctx) + otel.SetTracerProvider(tracenoop.NewTracerProvider()) + otel.SetMeterProvider(metricnoop.NewMeterProvider()) + }) +} + +func TestInit_NoOpWhenDisabled(t *testing.T) { + clearAllEnv(t) + resetTelemetryState(t) + if err := Init(context.Background(), "bd", "v0.0.0"); err != nil { + t.Fatalf("Init: %v", err) + } +} + +func TestInit_LegacyEnvActivatesAndWarns(t *testing.T) { + clearAllEnv(t) + resetTelemetryState(t) + t.Setenv("BD_OTEL_METRICS_URL", "http://example.invalid/metrics") + + origStderr := os.Stderr + r, w, err := os.Pipe() + if err != nil { + t.Fatalf("pipe: %v", err) + } + os.Stderr = w + t.Cleanup(func() { os.Stderr = origStderr }) + + if err := Init(context.Background(), "bd", "v0.0.0"); err != nil { + t.Fatalf("Init: %v", err) + } + _ = w.Close() + out, _ := io.ReadAll(r) + if !strings.Contains(string(out), "BD_OTEL_*") { + t.Errorf("expected BD_OTEL_* deprecation warning on stderr, got %q", string(out)) + } + if got := os.Getenv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"); got != "http://example.invalid/metrics" { + t.Errorf("legacy env should have populated OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, got %q", got) + } +} + +func TestInit_StdoutExporters(t *testing.T) { + clearAllEnv(t) + resetTelemetryState(t) + t.Setenv("BD_OTEL_ENABLED", "true") + t.Setenv("OTEL_TRACES_EXPORTER", "console") + t.Setenv("OTEL_METRICS_EXPORTER", "console") + + // Console exporters write to stdout on shutdown; redirect to keep test + // output pristine. + origStdout := os.Stdout + _, w, err := os.Pipe() + if err != nil { + t.Fatalf("pipe: %v", err) + } + os.Stdout = w + t.Cleanup(func() { + _ = w.Close() + os.Stdout = origStdout + }) + + if err := Init(context.Background(), "bd", "v0.0.0"); err != nil { + t.Fatalf("Init: %v", err) + } +} + +func TestOTLPMetricsEndpointSet(t *testing.T) { + cases := []struct { + name string + env map[string]string + want bool + }{ + {"none", nil, false}, + {"metrics-specific", map[string]string{"OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "http://example.invalid"}, true}, + {"generic", map[string]string{"OTEL_EXPORTER_OTLP_ENDPOINT": "http://example.invalid"}, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + clearAllEnv(t) + for k, v := range tc.env { + t.Setenv(k, v) + } + if got := otlpMetricsEndpointSet(); got != tc.want { + t.Errorf("otlpMetricsEndpointSet() = %v, want %v", got, tc.want) + } + }) + } +} + +func lookupAttr(kvs []attribute.KeyValue, key string) (attribute.Value, bool) { + for _, kv := range kvs { + if string(kv.Key) == key { + return kv.Value, true + } + } + return attribute.Value{}, false +} + +func containsSubstr(haystack []string, needle string) bool { + for _, s := range haystack { + if strings.Contains(s, needle) { + return true + } + } + return false +}