feat: add TLS configuration and fix version retrieval for OTel

- Add OTEL_EXPORTER_OTLP_INSECURE env var and --otel-insecure flag
- Default to secure TLS connections (production-ready)
- Fix version retrieval to use actual leeway.Version
- Update documentation with Honeycomb production examples
- Add TLS configuration section to observability docs

Addresses review feedback on PR #288

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

Author: corneliusludmann

README.md

@@ -607,25 +607,35 @@ Leeway supports distributed tracing using OpenTelemetry to provide visibility in
 Enable tracing by setting the OTLP endpoint:
 
 ```bash
+# Local development (Jaeger)
 export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318
+export OTEL_EXPORTER_OTLP_INSECURE=true
+leeway build :my-package
+
+# Production (Honeycomb)
+export OTEL_EXPORTER_OTLP_ENDPOINT=api.honeycomb.io:443
+export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=YOUR_API_KEY"
 leeway build :my-package
 ```
 
 Or using CLI flags:
 
 ```bash
-leeway build :my-package --otel-endpoint=localhost:4318
+leeway build :my-package --otel-endpoint=localhost:4318 --otel-insecure
 ```
 
 ## Environment Variables
 
 - `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP endpoint URL
+- `OTEL_EXPORTER_OTLP_INSECURE`: Disable TLS (`true` or `false`, default: `false`)
+- `OTEL_EXPORTER_OTLP_HEADERS`: Additional headers (e.g., API keys)
 - `TRACEPARENT`: W3C Trace Context traceparent header for distributed tracing
 - `TRACESTATE`: W3C Trace Context tracestate header
 
 ## CLI Flags
 
 - `--otel-endpoint`: OTLP endpoint URL (overrides environment variable)
+- `--otel-insecure`: Disable TLS for OTLP endpoint
 - `--trace-parent`: W3C traceparent header for parent trace context
 - `--trace-state`: W3C tracestate header
 
@@ -646,8 +656,9 @@ docker run -d --name jaeger \
   -p 16686:16686 \
   jaegertracing/all-in-one:latest
 
-# Build with tracing
+# Build with tracing (insecure for local development)
 export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318
+export OTEL_EXPORTER_OTLP_INSECURE=true
 leeway build :my-package
 
 # View traces at http://localhost:16686

cmd/build.go

@@ -214,6 +214,7 @@ func addBuildFlags(cmd *cobra.Command) {
 	cmd.Flags().Bool("fixed-build-dir", true, "Use a fixed build directory for each package, instead of based on the package version, to better utilize caches based on absolute paths (defaults to true)")
 	cmd.Flags().Bool("docker-export-to-cache", false, "Export Docker images to cache instead of pushing directly (enables SLSA L3 compliance)")
 	cmd.Flags().String("otel-endpoint", os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT"), "OpenTelemetry OTLP endpoint URL for tracing (defaults to $OTEL_EXPORTER_OTLP_ENDPOINT)")
+	cmd.Flags().Bool("otel-insecure", os.Getenv("OTEL_EXPORTER_OTLP_INSECURE") == "true", "Disable TLS for OTLP endpoint (for local development only, defaults to $OTEL_EXPORTER_OTLP_INSECURE)")
 	cmd.Flags().String("trace-parent", os.Getenv("TRACEPARENT"), "W3C Trace Context traceparent header for distributed tracing (defaults to $TRACEPARENT)")
 	cmd.Flags().String("trace-state", os.Getenv("TRACESTATE"), "W3C Trace Context tracestate header for distributed tracing (defaults to $TRACESTATE)")
 }
@@ -325,8 +326,17 @@ func getBuildOpts(cmd *cobra.Command) ([]leeway.BuildOption, cache.LocalCache, f
 	if otelEndpoint, err := cmd.Flags().GetString("otel-endpoint"); err != nil {
 		log.Fatal(err)
 	} else if otelEndpoint != "" {
-		// Initialize tracer with the provided endpoint
-		tp, err := telemetry.InitTracer(context.Background(), otelEndpoint)
+		// Set leeway version for telemetry
+		telemetry.SetLeewayVersion(leeway.Version)
+
+		// Get insecure flag
+		otelInsecure, err := cmd.Flags().GetBool("otel-insecure")
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		// Initialize tracer with the provided endpoint and TLS configuration
+		tp, err := telemetry.InitTracer(context.Background(), otelEndpoint, otelInsecure)
 		if err != nil {
 			log.WithError(err).Warn("failed to initialize OpenTelemetry tracer")
 		} else {

docs/observability.md

@@ -44,13 +44,15 @@ Leeway supports W3C Trace Context propagation, allowing builds to be part of lar
 
 ### Environment Variables
 
-- `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP endpoint URL (e.g., `localhost:4318`)
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP endpoint URL (e.g., `localhost:4318` or `api.honeycomb.io:443`)
+- `OTEL_EXPORTER_OTLP_INSECURE`: Disable TLS for OTLP endpoint (`true` or `false`, default: `false`)
 - `TRACEPARENT`: W3C Trace Context traceparent header (format: `00-{trace-id}-{span-id}-{flags}`)
 - `TRACESTATE`: W3C Trace Context tracestate header (optional)
 
 ### CLI Flags
 
 - `--otel-endpoint`: OTLP endpoint URL (overrides `OTEL_EXPORTER_OTLP_ENDPOINT`)
+- `--otel-insecure`: Disable TLS for OTLP endpoint (overrides `OTEL_EXPORTER_OTLP_INSECURE`)
 - `--trace-parent`: W3C traceparent header (overrides `TRACEPARENT`)
 - `--trace-state`: W3C tracestate header (overrides `TRACESTATE`)
 
@@ -61,6 +63,22 @@ CLI flags take precedence over environment variables:
 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:
+
+```bash
+# Local development (insecure)
+export OTEL_EXPORTER_OTLP_INSECURE=true
+export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318
+leeway build :my-package
+
+# Production (secure, 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
+```
+
 ## Span Attributes
 
 ### Root Span Attributes
@@ -165,13 +183,38 @@ docker run -d --name jaeger \
   -p 16686:16686 \
   jaegertracing/all-in-one:latest
 
-# Build with tracing
+# Build with tracing (insecure for local development)
 export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318
+export OTEL_EXPORTER_OTLP_INSECURE=true
 leeway build :my-package
 
 # View traces at http://localhost:16686
 ```
 
+### With Honeycomb (Production)
+
+```bash
+# Configure Honeycomb endpoint with API key
+export OTEL_EXPORTER_OTLP_ENDPOINT=api.honeycomb.io:443
+export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=YOUR_API_KEY"
+
+# Build with tracing (secure by default)
+leeway build :my-package
+
+# View traces in Honeycomb UI
+```
+
+### In CI/CD with Distributed Tracing
+
+```bash
+# Propagate trace context from parent CI system
+export OTEL_EXPORTER_OTLP_ENDPOINT=api.honeycomb.io:443
+export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=YOUR_API_KEY"
+export TRACEPARENT="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+
+leeway build :my-package
+```
+
 ## Error Handling
 
 Leeway implements graceful degradation for tracing:

pkg/leeway/telemetry/tracer.go

@@ -2,7 +2,6 @@ package telemetry
 
 import (
 	"context"
-	"os"
 	"strings"
 	"time"
 
@@ -16,19 +15,34 @@ import (
 	"golang.org/x/xerrors"
 )
 
+// leewayVersion is set by the build system and used for telemetry
+var leewayVersion = "unknown"
+
+// SetLeewayVersion sets the leeway version for telemetry reporting
+func SetLeewayVersion(version string) {
+	if version != "" {
+		leewayVersion = version
+	}
+}
+
 // InitTracer initializes the OpenTelemetry tracer with OTLP HTTP exporter.
 // The endpoint parameter specifies the OTLP endpoint URL (e.g., "localhost:4318").
+// The insecure parameter controls whether to use TLS (false = use TLS, true = no TLS).
 // Returns the TracerProvider which must be shut down when done.
-func InitTracer(ctx context.Context, endpoint string) (*sdktrace.TracerProvider, error) {
+func InitTracer(ctx context.Context, endpoint string, insecure bool) (*sdktrace.TracerProvider, error) {
 	if endpoint == "" {
 		return nil, xerrors.Errorf("OTLP endpoint not provided")
 	}
 
-	// Create OTLP HTTP exporter
-	exporter, err := otlptracehttp.New(ctx,
+	// Create OTLP HTTP exporter with optional TLS
+	opts := []otlptracehttp.Option{
 		otlptracehttp.WithEndpoint(endpoint),
-		otlptracehttp.WithInsecure(), // Use insecure for local development; configure TLS in production
-	)
+	}
+	if insecure {
+		opts = append(opts, otlptracehttp.WithInsecure())
+	}
+
+	exporter, err := otlptracehttp.New(ctx, opts...)
 	if err != nil {
 		return nil, xerrors.Errorf("failed to create OTLP exporter: %w", err)
 	}
@@ -114,14 +128,8 @@ func ParseTraceContext(traceparent, tracestate string) (context.Context, error)
 }
 
 // getLeewayVersion returns the leeway version for telemetry.
-// This is a placeholder that should be replaced with actual version retrieval.
 func getLeewayVersion() string {
-	// This will be imported from the leeway package
-	version := os.Getenv("LEEWAY_VERSION")
-	if version == "" {
-		version = "unknown"
-	}
-	return version
+	return leewayVersion
 }
 
 // FormatTraceContext formats a span context into W3C Trace Context format.

pkg/leeway/telemetry/tracer_test.go

@@ -167,7 +167,7 @@ func TestFormatTraceContext_Invalid(t *testing.T) {
 }
 
 func TestInitTracer_NoEndpoint(t *testing.T) {
-	_, err := InitTracer(context.Background(), "")
+	_, err := InitTracer(context.Background(), "", false)
 	if err == nil {
 		t.Error("InitTracer() should fail when endpoint is empty")
 	}