feat: add nested phase spans for OpenTelemetry tracing

Add PhaseAwareReporter optional interface to enable phase-level span
creation without breaking existing reporters. Phase spans are created
as children of package spans for detailed build timeline visualization.

Changes:
- Define PhaseAwareReporter interface with phase start/finish methods
- Implement phase span tracking in OTelReporter
- Modify executeBuildPhase to call phase-aware reporters via type assertion
- Remove phase duration attributes (now captured in nested spans)
- Add comprehensive phase span tests
- Update documentation with span hierarchy and phase attributes

Closes CLC-2107

Co-authored-by: Ona <no-reply@ona.com>

Author: 2 people

README.md

@@ -611,6 +611,25 @@ export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=YOUR_API_KEY"
 leeway build :my-package
 ```
 
+The OpenTelemetry SDK automatically reads standard `OTEL_EXPORTER_OTLP_*` environment variables.
+
+## Span Hierarchy
+
+Leeway creates a nested span hierarchy for detailed build timeline visualization:
+
+```
+leeway.build (root)
+├── leeway.package (component:package-1)
+│   ├── leeway.phase (prep)
+│   ├── leeway.phase (build)
+│   └── leeway.phase (test)
+└── leeway.package (component:package-2)
+    ├── leeway.phase (prep)
+    └── leeway.phase (build)
+```
+
+Each phase span captures timing, status, and errors for individual build phases (prep, pull, lint, test, build, package).
+
 See [docs/observability.md](docs/observability.md) for configuration, examples, and span attributes.
 
 # Provenance (SLSA) - EXPERIMENTAL

docs/observability.md

@@ -19,14 +19,24 @@ OpenTelemetry tracing in leeway captures:
 ```
 Root Span (leeway.build)
 ├── Package Span 1 (leeway.package)
+│   ├── Phase Span (leeway.phase: prep)
+│   ├── Phase Span (leeway.phase: pull)
+│   ├── Phase Span (leeway.phase: lint)
+│   ├── Phase Span (leeway.phase: test)
+│   ├── Phase Span (leeway.phase: build)
+│   └── Phase Span (leeway.phase: package)
 ├── Package Span 2 (leeway.package)
+│   ├── Phase Span (leeway.phase: prep)
+│   └── Phase Span (leeway.phase: build)
 └── Package Span N (leeway.package)
+    └── ...
 ```
 
 - **Root Span**: Created when `BuildStarted` is called, represents the entire build operation
 - **Package Spans**: Created for each package being built, as children of the root span
+- **Phase Spans**: Created for each build phase (prep, pull, lint, test, build, package) as children of package spans
 
-Build phase durations (prep, pull, lint, test, build, package) are captured as attributes on package spans, not as separate spans. This design provides lower overhead and simpler hierarchy while maintaining visibility into phase-level performance.
+Phase spans provide detailed timeline visualization and capture individual phase errors. Only phases with commands are executed and create spans.
 
 ### Context Propagation
 
@@ -35,6 +45,7 @@ Leeway supports W3C Trace Context propagation, allowing builds to be part of lar
 1. **Parent Context**: Accepts `traceparent` and `tracestate` headers from upstream systems
 2. **Root Context**: Creates a root span linked to the parent context
 3. **Package Context**: Each package span is a child of the root span
+4. **Phase Context**: Each phase span is a child of its package span
 
 ## Configuration
 
@@ -109,11 +120,24 @@ leeway build :my-package
 | `leeway.package.builddir` | string | Build directory | `"/tmp/leeway/build/..."` |
 | `leeway.package.last_phase` | string | Last completed phase | `"build"` |
 | `leeway.package.duration_ms` | int64 | Total build duration (ms) | `15234` |
-| `leeway.package.phase.{phase}.duration_ms` | int64 | Phase duration (ms) | `5432` |
 | `leeway.package.test.coverage_percentage` | int | Test coverage % | `85` |
 | `leeway.package.test.functions_with_test` | int | Functions with tests | `42` |
 | `leeway.package.test.functions_without_test` | int | Functions without tests | `8` |
 
+### Phase Span Attributes
+
+Phase spans are created for each build phase (prep, pull, lint, test, build, package) that has commands to execute.
+
+| Attribute | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `leeway.phase.name` | string | Phase name | `"prep"`, `"build"`, `"test"`, etc. |
+
+**Span Status:**
+- `OK`: Phase completed successfully
+- `ERROR`: Phase failed (error details in span events)
+
+**Span Duration:** The span's start and end times capture the phase execution duration automatically.
+
 ### GitHub Actions Attributes
 
 When running in GitHub Actions (`GITHUB_ACTIONS=true`), the following attributes are added to the root span:

pkg/leeway/build.go

@@ -1365,6 +1365,11 @@ func executeBuildPhase(buildctx *buildContext, p *Package, builddir string, bld
 		return nil
 	}
 
+	// Notify phase-aware reporters
+	if par, ok := buildctx.Reporter.(PhaseAwareReporter); ok {
+		par.PackageBuildPhaseStarted(p, phase)
+	}
+
 	if phase != PackageBuildPhasePrep {
 		pkgRep.phaseEnter[phase] = time.Now()
 		pkgRep.Phases = append(pkgRep.Phases, phase)
@@ -1375,6 +1380,11 @@ func executeBuildPhase(buildctx *buildContext, p *Package, builddir string, bld
 	err := executeCommandsForPackage(buildctx, p, builddir, cmds)
 	pkgRep.phaseDone[phase] = time.Now()
 
+	// Notify phase-aware reporters
+	if par, ok := buildctx.Reporter.(PhaseAwareReporter); ok {
+		par.PackageBuildPhaseFinished(p, phase, err)
+	}
+
 	return err
 }
 

pkg/leeway/reporter.go

@@ -52,6 +52,17 @@ type Reporter interface {
 	PackageBuildFinished(pkg *Package, rep *PackageBuildReport)
 }
 
+// PhaseAwareReporter is an optional interface that reporters can implement
+// to receive phase-level notifications for creating nested spans or tracking.
+// This follows the Go pattern of optional interfaces (like io.Closer, io.Seeker).
+type PhaseAwareReporter interface {
+	Reporter
+	// PackageBuildPhaseStarted is called when a build phase starts
+	PackageBuildPhaseStarted(pkg *Package, phase PackageBuildPhase)
+	// PackageBuildPhaseFinished is called when a build phase completes
+	PackageBuildPhaseFinished(pkg *Package, phase PackageBuildPhase, err error)
+}
+
 type PackageBuildReport struct {
 	phaseEnter map[PackageBuildPhase]time.Time
 	phaseDone  map[PackageBuildPhase]time.Time
@@ -701,6 +712,7 @@ type OTelReporter struct {
 	rootSpan     trace.Span
 	packageCtxs  map[string]context.Context
 	packageSpans map[string]trace.Span
+	phaseSpans   map[string]trace.Span // key: "packageName:phaseName"
 	mu           sync.RWMutex
 }
 
@@ -714,6 +726,7 @@ func NewOTelReporter(tracer trace.Tracer, parentCtx context.Context) *OTelReport
 		parentCtx:    parentCtx,
 		packageCtxs:  make(map[string]context.Context),
 		packageSpans: make(map[string]trace.Span),
+		phaseSpans:   make(map[string]trace.Span),
 	}
 }
 
@@ -866,16 +879,6 @@ func (r *OTelReporter) PackageBuildFinished(pkg *Package, rep *PackageBuildRepor
 		attribute.Int64("leeway.package.duration_ms", rep.TotalTime().Milliseconds()),
 	)
 
-	// Add phase durations
-	for _, phase := range rep.Phases {
-		duration := rep.PhaseDuration(phase)
-		if duration >= 0 {
-			span.SetAttributes(
-				attribute.Int64(fmt.Sprintf("leeway.package.phase.%s.duration_ms", phase), duration.Milliseconds()),
-			)
-		}
-	}
-
 	// Add test coverage if available
 	if rep.TestCoverageAvailable {
 		span.SetAttributes(
@@ -901,6 +904,70 @@ func (r *OTelReporter) PackageBuildFinished(pkg *Package, rep *PackageBuildRepor
 	delete(r.packageCtxs, pkgName)
 }
 
+// PackageBuildPhaseStarted implements PhaseAwareReporter
+func (r *OTelReporter) PackageBuildPhaseStarted(pkg *Package, phase PackageBuildPhase) {
+	if r.tracer == nil {
+		return
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	pkgName := pkg.FullName()
+	packageCtx, ok := r.packageCtxs[pkgName]
+	if !ok {
+		log.WithField("package", pkgName).Warn("PackageBuildPhaseStarted called without package context")
+		return
+	}
+
+	// Create phase span as child of package span
+	phaseKey := fmt.Sprintf("%s:%s", pkgName, phase)
+	ctx, span := r.tracer.Start(packageCtx, "leeway.phase",
+		trace.WithSpanKind(trace.SpanKindInternal),
+	)
+
+	// Add phase attributes
+	span.SetAttributes(
+		attribute.String("leeway.phase.name", string(phase)),
+	)
+
+	// Store phase span and update package context
+	r.phaseSpans[phaseKey] = span
+	r.packageCtxs[pkgName] = ctx
+}
+
+// PackageBuildPhaseFinished implements PhaseAwareReporter
+func (r *OTelReporter) PackageBuildPhaseFinished(pkg *Package, phase PackageBuildPhase, err error) {
+	if r.tracer == nil {
+		return
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	pkgName := pkg.FullName()
+	phaseKey := fmt.Sprintf("%s:%s", pkgName, phase)
+	span, ok := r.phaseSpans[phaseKey]
+	if !ok {
+		log.WithField("package", pkgName).WithField("phase", phase).Warn("PackageBuildPhaseFinished called without corresponding PackageBuildPhaseStarted")
+		return
+	}
+
+	// Set error status if phase failed
+	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+	} else {
+		span.SetStatus(codes.Ok, "phase completed successfully")
+	}
+
+	// End span
+	span.End()
+
+	// Clean up
+	delete(r.phaseSpans, phaseKey)
+}
+
 // addGitHubAttributes adds GitHub Actions context attributes to the span
 func (r *OTelReporter) addGitHubAttributes(span trace.Span) {
 	// Check if running in GitHub Actions