refactor(telemetry): adopt standard OTel SDK env vars with BD_OTEL_* back-compat (#3859)

* 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>
This commit is contained in:
Graeme Foster 2026-08-03 08:05:06 +01:00 • committed by GitHub
commit 1cf7490c71
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 744 additions and 86 deletions

View file

@ -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.<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)
}

View file

@ -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.<name>
// 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()
}

View file

@ -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)

View file

@ -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 {

View file

@ -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.

View file

@ -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))
}

View file

@ -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 == "" {

View file

@ -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
}