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:
parent
07f54894f4
commit
1cf7490c71
8 changed files with 744 additions and 86 deletions
71
cmd/bd/command_telemetry.go
Normal file
71
cmd/bd/command_telemetry.go
Normal 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)
|
||||
}
|
||||
84
cmd/bd/command_telemetry_test.go
Normal file
84
cmd/bd/command_telemetry_test.go
Normal 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()
|
||||
}
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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))
|
||||
}
|
||||
|
|
@ -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 == "" {
|
||||
|
|
|
|||
373
internal/telemetry/telemetry_test.go
Normal file
373
internal/telemetry/telemetry_test.go
Normal 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
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue