refactor: add CleanupFunc type alias and address review feedback

- Add CleanupFunc type alias for better self-documentation
- Fix typo: 'exprimental' -> 'experimental' in README
- Shorten OpenTelemetry section in README, link to detailed docs
- Add production security warning for TLS configuration
- Clarify design rationale for phase attributes vs spans
- Improve getLeewayVersion documentation

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

Author: corneliusludmann

README.md

@@ -596,29 +596,20 @@ variables have an effect on leeway:
 - `LEEWAY_CACHE_DIR`: Location of the local build cache. The directory does not have to exist yet.
 - `LEEWAY_BUILD_DIR`: Working location of leeway (i.e. where the actual builds happen). This location will see heavy I/O which makes it advisable to place this on a fast SSD or in RAM.
 - `LEEWAY_YARN_MUTEX`: Configures the mutex flag leeway will pass to yarn. Defaults to "network". See https://yarnpkg.com/lang/en/docs/cli/#toc-concurrency-and-mutex for possible values.
-- `LEEWAY_EXPERIMENTAL`: Enables exprimental features
+- `LEEWAY_EXPERIMENTAL`: Enables experimental features
 
 # OpenTelemetry Tracing
 
 Leeway supports distributed tracing using OpenTelemetry for build performance visibility.
 
-## Quick Start
-
 ```bash
-# Local development (Jaeger)
-export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318
-export OTEL_EXPORTER_OTLP_INSECURE=true
-leeway build :my-package
-
-# Production (Honeycomb with API key)
+# Enable tracing by setting OTLP endpoint
 export OTEL_EXPORTER_OTLP_ENDPOINT=api.honeycomb.io:443
 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.
-
-**For detailed configuration, examples, and span attributes, see [docs/observability.md](docs/observability.md).**
+See [docs/observability.md](docs/observability.md) for configuration, examples, and span attributes.
 
 # Provenance (SLSA) - EXPERIMENTAL
 leeway can produce provenance information as part of a build. At the moment only [SLSA Provenance v0.2](https://slsa.dev/provenance/v0.2) is supported. This support is **experimental**.

cmd/build.go

@@ -23,6 +23,9 @@ import (
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
 )
 
+// CleanupFunc is a function that performs cleanup operations and must be deferred
+type CleanupFunc func()
+
 // buildCmd represents the build command
 var buildCmd = &cobra.Command{
 	Use:   "build [targetPackage]",
@@ -219,7 +222,7 @@ func addBuildFlags(cmd *cobra.Command) {
 	cmd.Flags().String("trace-state", os.Getenv("TRACESTATE"), "W3C Trace Context tracestate header for distributed tracing (defaults to $TRACESTATE)")
 }
 
-func getBuildOpts(cmd *cobra.Command) ([]leeway.BuildOption, cache.LocalCache, func()) {
+func getBuildOpts(cmd *cobra.Command) ([]leeway.BuildOption, cache.LocalCache, CleanupFunc) {
 	// Track if user explicitly set LEEWAY_DOCKER_EXPORT_TO_CACHE before workspace loading.
 	// This allows us to distinguish:
 	// - User set explicitly: High priority (overrides package config)

docs/observability.md

@@ -26,7 +26,7 @@ Root Span (leeway.build)
 - **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
 
-Build phase durations (prep, pull, lint, test, build, package) are captured as attributes on package spans, not as separate 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.
 
 ### Context Propagation
 
@@ -65,15 +65,19 @@ CLI flag → Environment variable → Default (disabled)
 
 ### TLS Configuration
 
-By default, leeway uses **secure TLS connections** to the OTLP endpoint. For local development with tools like Jaeger, you can disable TLS:
+By default, leeway uses **secure TLS connections** to the OTLP endpoint. 
+
+⚠️ **Production**: Always use secure TLS (default). Never set `OTEL_EXPORTER_OTLP_INSECURE=true` in production environments.
+
+For local development with tools like Jaeger, you can disable TLS:
 
 ```bash
-# Local development (insecure)
+# Local development (insecure - for testing only)
 export OTEL_EXPORTER_OTLP_INSECURE=true
 export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318
 leeway build :my-package
 
-# Production (secure, default)
+# Production (secure TLS, default)
 export OTEL_EXPORTER_OTLP_ENDPOINT=api.honeycomb.io:443
 export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=YOUR_API_KEY"
 leeway build :my-package

pkg/leeway/telemetry/tracer.go

@@ -127,7 +127,8 @@ func ParseTraceContext(traceparent, tracestate string) (context.Context, error)
 	return ctx, nil
 }
 
-// getLeewayVersion returns the leeway version for telemetry.
+// getLeewayVersion returns the leeway version set via SetLeewayVersion.
+// Returns "unknown" if version was not set.
 func getLeewayVersion() string {
 	return leewayVersion
 }