* refactor(telemetry): adopt standard OpenTelemetry SDK env vars with explicit BD_OTEL_ENABLED gate
Telemetry configuration moves from BD_OTEL_* data variables to the
standard OTEL_* environment variables. Activation now requires
BD_OTEL_ENABLED=true so a machine-global OTEL_* setting (for some other
instrumented tool) cannot silently turn bd telemetry on.
The resource picks up resource.WithFromEnv() so OTEL_SERVICE_NAME and
OTEL_RESOURCE_ATTRIBUTES take effect — users can override service.name
or stamp deployment.environment without forking.
Backwards compatibility: BD_OTEL_METRICS_URL, BD_OTEL_LOGS_URL, and
BD_OTEL_STDOUT continue to work and activate telemetry on their own.
Each translates to its OTEL_* equivalent unconditionally — a legacy
value wins over a pre-existing OTEL_* value so cross-tool environments
don't redirect bd traffic. Every invocation that sees a BD_OTEL_*
variable logs a one-line deprecation warning to stderr.
OTLP endpoint discovery is delegated to the SDK; the explicit URL
helper in internal/telemetry/otlp.go is removed.
OTEL_SDK_DISABLED=true forces telemetry off even when an opt-in is in
effect, matching SDK conventions.
Tests cover: legacy var translation + override semantics, master-switch
activation, OTEL_*-alone-doesn't-activate, OTEL_SDK_DISABLED override,
WithFromEnv resource attribute merge, deprecation warning emission, and
otlpMetricsEndpointSet detection (specific endpoint, generic endpoint,
negative).
Part of the gastownhall/beads PR #3475 split: isolates the OTEL_* env
var standardisation from the WrapStorage wiring (#3858) and the
bd.prefix attribute work (separate follow-up).
* refactor(cmd/bd): extract command-telemetry wiring into testable helpers
cmd/bd/main.go's PreRunE block contained two pieces of OTel wiring —
telemetry.Init and the bd.command.<name> root span construction — that
silently decay if a future refactor drops them. Same regression class
as the WrapStorage bug (telemetry implemented but never called) —
wiring buried in cobra PreRunE escapes review.
Extract two helpers in cmd/bd/command_telemetry.go:
- commandSpanAttrs(cmdName, version, args): pure function returning
the initial attribute set for the bd.command.<name> span. The
bd.actor attribute is stamped later via SetAttributes once
getActorWithGit() resolves.
- startCommandTelemetry(...): composes Init + Tracer.Start. Single
callable line in main.go.
Three tests cover the commandSpanAttrs output (full attrs and the
empty-args edge case) and the startCommandTelemetry wiring contract:
it must always return a non-nil context and span, since the
bd.command.<name> span is the parent for every storage and AI span
downstream — silently returning nil would break trace nesting across
the whole invocation. Whether the span actually records is governed
by telemetry.Init which is covered in internal/telemetry/telemetry_test.go.
main.go shrinks by 10 lines.
* fixup(cmd/bd): stage command_telemetry.go split omitted from merge commit
The previous merge commit (def9f97a4) resolved main.go's PersistentPreRunE
conflict to call initTelemetry()/startCommandSpan() but the working-tree edit
to cmd/bd/command_telemetry.go that defines those two helpers was never
staged, so the merge commit as recorded does not compile:
cmd/bd/main.go:680:3: undefined: initTelemetry
cmd/bd/main.go:706:26: undefined: startCommandSpan
This stages that omitted edit: command_telemetry.go now defines
initTelemetry (the Init half) and startCommandSpan (the span-start half,
using commandSpanAttrs) as separate functions, with startCommandTelemetry
kept as their combined form for callers/tests that don't need to interleave
other setup between the two steps. See the merge commit message for why the
split is necessary (main's usage-metrics bootstrap block sits between the
two steps for one internal subcommand).
Verified: CGO_ENABLED=0 go build -tags gms_pure_go ./... now succeeds.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(telemetry): gate the OTLP metric exporter on OTEL_METRICS_EXPORTER
A console-only or none selection — including the legacy BD_OTEL_STDOUT=true
translation — previously still installed an OTLP reader whenever a
machine-global OTEL_EXPORTER_OTLP_ENDPOINT existed, silently exporting bd
metrics to an endpoint configured for some other tool. The selector is now
parsed per the SDK spec (comma-separated; unset defaults to otlp; none
disables) and the OTLP reader requires the selection to include otlp.
The BD_OTEL_STDOUT translation keeps both destinations when
BD_OTEL_METRICS_URL is also set (console,otlp), preserving the existing
both-exporters behavior for that combination.
Also bound the test-cleanup Shutdown with a 2s context so suites configured
with unreachable endpoints (example.invalid) don't spend ~30s in OTLP
retries.
Both issues found by a cross-vendor (Codex) review of the rebased branch.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
71 lines
3.3 KiB
Go
71 lines
3.3 KiB
Go
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.<name>
|
|
// 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.<name> 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)
|
|
}
|