Add tracing manifests and docs; clean up branch lint findings

Manager env block (downward-API resource attrs, commented OTLP
examples), architecture §10 + Decisions entries, README section.
Lint: goconst constants, gofmt, logcheck (Setup now takes its logger
from ctx via logf.FromContext).

Co-Authored-By: Claude <noreply@anthropic.com>

internal/provider/metrics.go

@@ -50,17 +50,25 @@ func (i *instrumented) record(op string, err error) {
 	i.rec.ProviderRequest(i.name, op, resultLabel(err))
 }
 
+const (
+	resultOK            = "ok"
+	resultNotFound      = "not_found"
+	resultQuotaExceeded = "quota_exceeded"
+	resultPermanent     = "permanent"
+	resultTransient     = "transient"
+)
+
 func resultLabel(err error) string {
 	switch Class(err) {
 	case nil:
-		return "ok"
+		return resultOK
 	case ErrNotFound:
-		return "not_found"
+		return resultNotFound
 	case ErrQuotaExceeded:
-		return "quota_exceeded"
+		return resultQuotaExceeded
 	case ErrPermanent:
-		return "permanent"
+		return resultPermanent
 	default:
-		return "transient"
+		return resultTransient
 	}
 }

internal/provider/tracing_test.go

@@ -33,7 +33,7 @@ func TestWithTracing_spanPerCall(t *testing.T) {
 			call:       func(p Provider) error { _, err := p.Create(context.Background(), CreateRequest{}); return err },
 			wantSpan:   "provider.create",
 			wantStatus: codes.Ok,
-			wantResult: "ok",
+			wantResult: resultOK,
 			wantAttr:   attribute.String("provider.id", "id-1"),
 		},
 		{
@@ -42,7 +42,7 @@ func TestWithTracing_spanPerCall(t *testing.T) {
 			call:       func(p Provider) error { _, err := p.Get(context.Background(), "id-1"); return err },
 			wantSpan:   "provider.get",
 			wantStatus: codes.Ok,
-			wantResult: "not_found",
+			wantResult: resultNotFound,
 			wantAttr:   attribute.String("provider.id", "id-1"),
 		},
 		{
@@ -51,7 +51,7 @@ func TestWithTracing_spanPerCall(t *testing.T) {
 			call:       func(p Provider) error { return p.Delete(context.Background(), "id-1") },
 			wantSpan:   "provider.delete",
 			wantStatus: codes.Error,
-			wantResult: "transient",
+			wantResult: resultTransient,
 			wantAttr:   attribute.String("provider.id", "id-1"),
 		},
 		{
@@ -60,7 +60,7 @@ func TestWithTracing_spanPerCall(t *testing.T) {
 			call:       func(p Provider) error { _, err := p.Create(context.Background(), CreateRequest{}); return err },
 			wantSpan:   "provider.create",
 			wantStatus: codes.Error,
-			wantResult: "quota_exceeded",
+			wantResult: resultQuotaExceeded,
 			wantAttr:   attribute.String("provider.name", "x"),
 		},
 		{
@@ -69,7 +69,7 @@ func TestWithTracing_spanPerCall(t *testing.T) {
 			call:       func(p Provider) error { _, err := p.ListByTag(context.Background()); return err },
 			wantSpan:   "provider.list",
 			wantStatus: codes.Ok,
-			wantResult: "ok",
+			wantResult: resultOK,
 			wantAttr:   attribute.Int("provider.instances", 0),
 		},
 	}

internal/tracing/logger.go

@@ -47,6 +47,8 @@ func StartSpan(ctx context.Context, tracer trace.Tracer, name string, opts ...tr
 // base for span enrichment. If ctx already carries a valid span (the HTTP
 // middleware calls this inside the otelhttp handler), the logger is
 // enriched immediately.
+//
+//nolint:logcheck // IntoContext-analogue: taking ctx and the logger to seed it with is the point.
 func ContextWithLogger(ctx context.Context, base logr.Logger) context.Context {
 	ctx = context.WithValue(ctx, baseLoggerKey{}, base)
 	if sc := trace.SpanContextFromContext(ctx); sc.IsValid() {

internal/tracing/tracing.go

@@ -10,7 +10,6 @@ import (
 	"os"
 	"strings"
 
-	"github.com/go-logr/logr"
 	"go.opentelemetry.io/otel"
 	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
 	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
@@ -19,6 +18,20 @@ import (
 	"go.opentelemetry.io/otel/sdk/resource"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
 	semconv "go.opentelemetry.io/otel/semconv/v1.43.0"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+)
+
+const (
+	envSDKDisabled        = "OTEL_SDK_DISABLED"
+	envTracesExporter     = "OTEL_TRACES_EXPORTER"
+	envOTLPEndpoint       = "OTEL_EXPORTER_OTLP_ENDPOINT"
+	envOTLPTracesEndpoint = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
+	envOTLPProtocol       = "OTEL_EXPORTER_OTLP_PROTOCOL"
+	envOTLPTracesProtocol = "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"
+
+	exporterOTLP    = "otlp"
+	exporterConsole = "console"
+	exporterNone    = "none"
 )
 
 // maxQueueSize bounds the batch processor's span buffer; the default 2048
@@ -35,15 +48,19 @@ const maxQueueSize = 512
 // OTEL_TRACES_EXPORTER=none force it off (the Go SDK does not implement
 // OTEL_SDK_DISABLED itself). Sampling, endpoints, TLS, and headers follow
 // the standard SDK/exporter env vars (OTEL_TRACES_SAMPLER, OTEL_EXPORTER_OTLP_*).
-func Setup(ctx context.Context, log logr.Logger, service, version string) (func(context.Context) error, error) {
+//
+// Setup logs via the logger in ctx (logf.FromContext) rather than a
+// parameter — the caller seeds it with logf.IntoContext.
+func Setup(ctx context.Context, service, version string) (func(context.Context) error, error) {
+	log := logf.FromContext(ctx)
 	noop := func(context.Context) error { return nil }
 
-	exporterEnv := strings.ToLower(strings.TrimSpace(os.Getenv("OTEL_TRACES_EXPORTER")))
-	endpointSet := os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT") != "" ||
-		os.Getenv("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT") != ""
-	sdkDisabled := strings.EqualFold(strings.TrimSpace(os.Getenv("OTEL_SDK_DISABLED")), "true")
+	exporterEnv := strings.ToLower(strings.TrimSpace(os.Getenv(envTracesExporter)))
+	endpointSet := os.Getenv(envOTLPEndpoint) != "" ||
+		os.Getenv(envOTLPTracesEndpoint) != ""
+	sdkDisabled := strings.EqualFold(strings.TrimSpace(os.Getenv(envSDKDisabled)), "true")
 
-	if sdkDisabled || exporterEnv == "none" || (exporterEnv == "" && !endpointSet) {
+	if sdkDisabled || exporterEnv == exporterNone || (exporterEnv == "" && !endpointSet) {
 		log.Info("tracing disabled",
 			"reason", disabledReason(sdkDisabled, exporterEnv))
 		return noop, nil
@@ -87,7 +104,7 @@ func disabledReason(sdkDisabled bool, exporterEnv string) string {
 	switch {
 	case sdkDisabled:
 		return "OTEL_SDK_DISABLED=true"
-	case exporterEnv == "none":
+	case exporterEnv == exporterNone:
 		return "OTEL_TRACES_EXPORTER=none"
 	default:
 		return "no OTEL_TRACES_EXPORTER or OTLP endpoint configured"
@@ -99,10 +116,10 @@ func disabledReason(sdkDisabled bool, exporterEnv string) string {
 // metric/log/prometheus exporters into a trace-only binary.
 func newExporter(ctx context.Context, kind string) (sdktrace.SpanExporter, string, error) {
 	switch kind {
-	case "", "otlp":
-		proto := strings.ToLower(strings.TrimSpace(os.Getenv("OTEL_EXPORTER_OTLP_TRACES_PROTOCOL")))
+	case "", exporterOTLP:
+		proto := strings.ToLower(strings.TrimSpace(os.Getenv(envOTLPTracesProtocol)))
 		if proto == "" {
-			proto = strings.ToLower(strings.TrimSpace(os.Getenv("OTEL_EXPORTER_OTLP_PROTOCOL")))
+			proto = strings.ToLower(strings.TrimSpace(os.Getenv(envOTLPProtocol)))
 		}
 		switch proto {
 		case "", "http/protobuf":
@@ -114,9 +131,9 @@ func newExporter(ctx context.Context, kind string) (sdktrace.SpanExporter, strin
 		default:
 			return nil, "", fmt.Errorf("unsupported OTLP protocol %q (supported: http/protobuf, grpc)", proto)
 		}
-	case "console":
+	case exporterConsole:
 		exp, err := stdouttrace.New()
-		return exp, "console", err
+		return exp, exporterConsole, err
 	default:
 		return nil, "", fmt.Errorf("unsupported OTEL_TRACES_EXPORTER %q (supported: otlp, console, none)", kind)
 	}

internal/tracing/tracing_test.go

@@ -5,24 +5,25 @@ import (
 	"testing"
 	"time"
 
-	"github.com/go-logr/logr"
 	"go.opentelemetry.io/otel"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
 	"go.opentelemetry.io/otel/trace/noop"
 )
 
+const testOTLPEndpoint = "http://localhost:4318"
+
 // clearOTelEnv pins every env var Setup reads, so developer shells with
 // OTEL_* set can't change test outcomes. Not parallel-safe by design
 // (t.Setenv forbids t.Parallel).
 func clearOTelEnv(t *testing.T) {
 	t.Helper()
 	for _, k := range []string{
-		"OTEL_SDK_DISABLED",
-		"OTEL_TRACES_EXPORTER",
-		"OTEL_EXPORTER_OTLP_ENDPOINT",
-		"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
-		"OTEL_EXPORTER_OTLP_PROTOCOL",
-		"OTEL_EXPORTER_OTLP_TRACES_PROTOCOL",
+		envSDKDisabled,
+		envTracesExporter,
+		envOTLPEndpoint,
+		envOTLPTracesEndpoint,
+		envOTLPProtocol,
+		envOTLPTracesProtocol,
 	} {
 		t.Setenv(k, "")
 	}
@@ -38,50 +39,50 @@ func TestSetup_envGating(t *testing.T) {
 		{name: "no env means disabled", env: nil, wantEnabled: false},
 		{
 			name:        "endpoint enables otlp",
-			env:         map[string]string{"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"},
+			env:         map[string]string{envOTLPEndpoint: testOTLPEndpoint},
 			wantEnabled: true,
 		},
 		{
 			name:        "traces endpoint enables otlp",
-			env:         map[string]string{"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": "http://localhost:4318"},
+			env:         map[string]string{envOTLPTracesEndpoint: testOTLPEndpoint},
 			wantEnabled: true,
 		},
 		{
 			name:        "explicit console exporter",
-			env:         map[string]string{"OTEL_TRACES_EXPORTER": "console"},
+			env:         map[string]string{envTracesExporter: exporterConsole},
 			wantEnabled: true,
 		},
 		{
 			name:        "grpc protocol",
-			env:         map[string]string{"OTEL_TRACES_EXPORTER": "otlp", "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc"},
+			env:         map[string]string{envTracesExporter: exporterOTLP, envOTLPProtocol: "grpc"},
 			wantEnabled: true,
 		},
 		{
 			name: "exporter none wins over endpoint",
 			env: map[string]string{
-				"OTEL_TRACES_EXPORTER":        "none",
-				"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
+				envTracesExporter: exporterNone,
+				envOTLPEndpoint:   testOTLPEndpoint,
 			},
 			wantEnabled: false,
 		},
 		{
 			name: "OTEL_SDK_DISABLED wins over everything",
 			env: map[string]string{
-				"OTEL_SDK_DISABLED":           "true",
-				"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
+				envSDKDisabled:  "true",
+				envOTLPEndpoint: testOTLPEndpoint,
 			},
 			wantEnabled: false,
 		},
 		{
 			name:    "unsupported exporter errors",
-			env:     map[string]string{"OTEL_TRACES_EXPORTER": "jaeger"},
+			env:     map[string]string{envTracesExporter: "jaeger"},
 			wantErr: true,
 		},
 		{
 			name: "unsupported protocol errors",
 			env: map[string]string{
-				"OTEL_TRACES_EXPORTER":         "otlp",
-				"OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
+				envTracesExporter: exporterOTLP,
+				envOTLPProtocol:   "http/json",
 			},
 			wantErr: true,
 		},
@@ -100,7 +101,7 @@ func TestSetup_envGating(t *testing.T) {
 			before := noop.NewTracerProvider()
 			otel.SetTracerProvider(before)
 
-			shutdown, err := Setup(context.Background(), logr.Discard(), "test-svc", "abc123")
+			shutdown, err := Setup(context.Background(), "test-svc", "abc123")
 			if tc.wantErr {
 				if err == nil {
 					t.Fatal("want error, got nil")