feat(embed): add TelemetrySettings provider bundle + NopTelemetry (PIPE-1066)

embed/telemetry.go

@@ -0,0 +1,49 @@
+package embed
+
+import (
+	"go.opentelemetry.io/otel/metric"
+	metricnoop "go.opentelemetry.io/otel/metric/noop"
+	"go.opentelemetry.io/otel/trace"
+	tracenoop "go.opentelemetry.io/otel/trace/noop"
+	"go.uber.org/zap"
+)
+
+// TelemetrySettings bundles the OTel providers and logger blitz uses to emit
+// its own self-telemetry. It is the single value threaded from a host (or the
+// standalone CLI) down through module construction, so every generator, output,
+// and the runtime records to the same providers.
+//
+// Every field is optional. A nil provider means "fall back to the process
+// global" (via the generated NewMetrics and, in later phases, the tracer and
+// logger constructors), so a zero-value bundle behaves exactly as blitz did
+// before providers were injectable.
+type TelemetrySettings struct {
+	// Logger is blitz's internal diagnostic logger. Nil means callers supply
+	// their own fallback (a nop logger).
+	Logger *zap.Logger
+
+	// MeterProvider is the source of blitz's internal metric instruments. Nil
+	// falls back to otel.GetMeterProvider().
+	MeterProvider metric.MeterProvider
+
+	// TracerProvider is the source of blitz's internal spans. Nil falls back to
+	// otel.GetTracerProvider().
+	TracerProvider trace.TracerProvider
+
+	// PerBatchSpans enables the higher-volume per-emit-cycle spans. Off by
+	// default; the always-on coarse spans do not depend on it.
+	PerBatchSpans bool
+}
+
+// NopTelemetry returns a TelemetrySettings wired to no-op providers and a nop
+// logger. Use it where a caller has no telemetry to route, most commonly in
+// tests and in construction paths that record nothing. It is distinct from a
+// zero-value bundle: NopTelemetry emits to no-op providers, while a zero-value
+// bundle's nil fields fall back to the process globals.
+func NopTelemetry() TelemetrySettings {
+	return TelemetrySettings{
+		Logger:         zap.NewNop(),
+		MeterProvider:  metricnoop.NewMeterProvider(),
+		TracerProvider: tracenoop.NewTracerProvider(),
+	}
+}

embed/telemetry_test.go

@@ -0,0 +1,30 @@
+package embed
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNopTelemetry(t *testing.T) {
+	tel := NopTelemetry()
+
+	// Every provider and the logger must be non-nil so callers can use the
+	// bundle without nil checks.
+	require.NotNil(t, tel.Logger)
+	require.NotNil(t, tel.MeterProvider)
+	require.NotNil(t, tel.TracerProvider)
+
+	// Per-batch spans default off.
+	require.False(t, tel.PerBatchSpans)
+}
+
+func TestTelemetrySettings_zeroValueFieldsAreNil(t *testing.T) {
+	// A zero-value bundle leaves providers nil; components and NewMetrics are
+	// responsible for the nil->global fallback. This documents that contract.
+	var tel TelemetrySettings
+
+	require.Nil(t, tel.Logger)
+	require.Nil(t, tel.MeterProvider)
+	require.Nil(t, tel.TracerProvider)
+}

go.mod

@@ -24,6 +24,7 @@ require (
 	go.opentelemetry.io/otel/metric v1.44.0
 	go.opentelemetry.io/otel/sdk v1.44.0
 	go.opentelemetry.io/otel/sdk/metric v1.44.0
+	go.opentelemetry.io/otel/trace v1.44.0
 	go.opentelemetry.io/proto/otlp v1.11.0
 	go.uber.org/zap v1.28.0
 	golang.org/x/sys v0.47.0
@@ -86,7 +87,6 @@ require (
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 // indirect
-	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.uber.org/multierr v1.10.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/crypto v0.54.0 // indirect