feat: context-first logging API with enhanced env var support

Breaking API changes:
- All log methods now require context.Context as first parameter
- Removed WithContext() method - context passed directly to log calls

New features:
- InitFromEnv() now reads 8 env vars: LOG_LEVEL, LOG_DEVELOPMENT,
  SERVICE_NAME, SERVICE_VERSION, OTEL_ENDPOINT, OTEL_INSECURE,
  OTEL_USERNAME, OTEL_PASSWORD
- Performance optimization: skip context extraction for context.Background()
- Added BenchmarkContextExtraction for traced vs untraced paths

Documentation:
- Complete README rewrite with env vars, config reference, team patterns
- Updated doc.go with full env var list
- Added docs/PERFORMANCE_NOTES.md for optimization decisions
- Added docs/RFC_MULTI_FILE_LOGGING.md for future feature planning

Performance (M2 Mac):
- Background context: 1 alloc, ~50ns/op
- With trace context: 2 allocs, ~170ns/op

Author: i-naman

README.md

@@ -190,29 +190,51 @@ func (c Config) WithFile(path string) Config {
 }
 
 // InitFromEnv initializes a logger using environment variables.
+// This is the recommended way to configure ion in production deployments.
+//
 // Supported variables:
 //   - LOG_LEVEL: debug, info, warn, error (default: info)
-//   - SERVICE_NAME: name of the service (default: unknown)
 //   - LOG_DEVELOPMENT: "true" for pretty console output
-//   - OTEL_ENDPOINT: if set, enables OpenTelemetry export
+//   - SERVICE_NAME: name of the service (default: unknown)
+//   - SERVICE_VERSION: version of the service
+//   - OTEL_ENDPOINT: collector address, enables OTEL if set (e.g., "localhost:4317")
+//   - OTEL_INSECURE: "true" to disable TLS for OTEL connection
+//   - OTEL_USERNAME: Basic Auth username for OTEL collector
+//   - OTEL_PASSWORD: Basic Auth password for OTEL collector
 func InitFromEnv() Logger {
 	cfg := Default()
 
+	// Core settings
 	if val := os.Getenv("LOG_LEVEL"); val != "" {
 		cfg.Level = val
 	}
 	if val := os.Getenv("SERVICE_NAME"); val != "" {
 		cfg.ServiceName = val
 	}
+	if val := os.Getenv("SERVICE_VERSION"); val != "" {
+		cfg.Version = val
+	}
 	if os.Getenv("LOG_DEVELOPMENT") == "true" {
 		cfg.Development = true
 		cfg.Console.Format = "pretty"
 	}
+
+	// OTEL settings
 	if val := os.Getenv("OTEL_ENDPOINT"); val != "" {
 		cfg.OTEL.Enabled = true
 		cfg.OTEL.Endpoint = val
 	}
+	if os.Getenv("OTEL_INSECURE") == "true" {
+		cfg.OTEL.Insecure = true
+	}
+	if val := os.Getenv("OTEL_USERNAME"); val != "" {
+		cfg.OTEL.Username = val
+	}
+	if val := os.Getenv("OTEL_PASSWORD"); val != "" {
+		cfg.OTEL.Password = val
+	}
 
+	// Create logger with OTEL if configured
 	if cfg.OTEL.Enabled && cfg.OTEL.Endpoint != "" {
 		l, err := NewWithOTEL(cfg)
 		if err == nil {

config.go

@@ -4,11 +4,15 @@ import (
 	"context"
 
 	"go.opentelemetry.io/otel/trace"
+	"go.uber.org/zap"
 )
 
-// Context keys for custom values.
+// contextKey is an unexported type for context keys defined in this package.
+// This prevents collisions with keys defined in other packages.
 type contextKey string
 
+// Context keys for storing log-relevant values in context.Context.
+// These values are automatically extracted and added to log entries.
 const (
 	requestIDKey contextKey = "request_id"
 	userIDKey    contextKey = "user_id"
@@ -17,7 +21,7 @@ const (
 )
 
 // WithRequestID adds a request ID to the context.
-// This ID will be automatically included in logs via WithContext().
+// This ID will be automatically included in logs.
 func WithRequestID(ctx context.Context, requestID string) context.Context {
 	return context.WithValue(ctx, requestIDKey, requestID)
 }
@@ -48,40 +52,40 @@ func UserIDFromContext(ctx context.Context) string {
 	return ""
 }
 
-// extractContextFields pulls trace/span IDs and custom values from context.
-// Called by WithContext() to automatically add context fields to logs.
-func extractContextFields(ctx context.Context) []Field {
+// extractContextZapFields pulls trace/span IDs and custom values from context.
+// Returns zap.Field slice directly for use in log methods (avoids Field conversion).
+func extractContextZapFields(ctx context.Context) []zap.Field {
 	if ctx == nil {
 		return nil
 	}
 
-	fields := make([]Field, 0, 4)
+	fields := make([]zap.Field, 0, 4)
 
 	// Extract OTEL trace context (if available)
 	spanCtx := trace.SpanContextFromContext(ctx)
 	if spanCtx.IsValid() {
 		fields = append(fields,
-			String("trace_id", spanCtx.TraceID().String()),
-			String("span_id", spanCtx.SpanID().String()),
+			zap.String("trace_id", spanCtx.TraceID().String()),
+			zap.String("span_id", spanCtx.SpanID().String()),
 		)
 	} else {
 		// Fallback to manual trace ID if set
 		if traceID, ok := ctx.Value(traceIDKey).(string); ok && traceID != "" {
-			fields = append(fields, String("trace_id", traceID))
+			fields = append(fields, zap.String("trace_id", traceID))
 		}
 		if spanID, ok := ctx.Value(spanIDKey).(string); ok && spanID != "" {
-			fields = append(fields, String("span_id", spanID))
+			fields = append(fields, zap.String("span_id", spanID))
 		}
 	}
 
 	// Extract request ID
 	if reqID, ok := ctx.Value(requestIDKey).(string); ok && reqID != "" {
-		fields = append(fields, String("request_id", reqID))
+		fields = append(fields, zap.String("request_id", reqID))
 	}
 
 	// Extract user ID
 	if userID, ok := ctx.Value(userIDKey).(string); ok && userID != "" {
-		fields = append(fields, String("user_id", userID))
+		fields = append(fields, zap.String("user_id", userID))
 	}
 
 	return fields

context.go

@@ -1,36 +1,85 @@
-// Package ion provides an enterprise-grade structured logger tailored for JupiterMeta blockchain services.
+// Package ion provides enterprise-grade structured logging for JupiterMeta blockchain services.
 //
-// It wraps the high-performance Zap logger and OpenTelemetry (OTEL) for observability, offering a simple
-// yet powerful API for consistent logging across microservices.
+// Ion wraps the high-performance [Zap] logger with [OpenTelemetry] integration,
+// offering a simple yet powerful API for consistent, observable logging across microservices.
 //
 // # Key Features
 //
-//   - Zero-allocation hot paths using a custom Zap core.
-//   - Built-in OpenTelemetry (OTEL) integration for log export.
-//   - Automatic context propagation (Trace ID, Span ID).
-//   - Specialized field helpers for blockchain primitives (TxHash, Slot, ShardID).
-//   - Configurable output formats (JSON for production, Pretty for development).
-//   - Log rotation and compression via lumberjack.
+//   - Pool-optimized hot paths with minimal allocations
+//   - Built-in OpenTelemetry (OTEL) integration for log export
+//   - Automatic context propagation (trace_id, span_id)
+//   - Specialized field helpers for blockchain primitives (TxHash, Slot, ShardID)
+//   - Configurable output formats (JSON for production, Pretty for development)
+//   - Log rotation and compression via lumberjack
 //
-// # Basic Usage
+// # Quick Start
 //
-// Initialize the logger with a configuration:
+// Global logger pattern (recommended for applications):
 //
-//	import "github.com/JupiterMetaLabs/ion"
+//	package main
+//
+//	import (
+//	    "context"
+//
+//	    "github.com/JupiterMetaLabs/ion"
+//	)
 //
 //	func main() {
-//	    logger := ion.New(ion.Default())
-//	    defer logger.Sync()
+//	    ctx := context.Background()
+//
+//	    ion.SetGlobal(ion.InitFromEnv())
+//	    defer ion.Sync()
+//
+//	    ion.Info(ctx, "application started", ion.String("version", "1.0.0"))
+//	}
+//
+// # Dependency Injection
+//
+// For libraries or explicit dependencies, pass [Logger] directly:
+//
+//	func NewServer(logger ion.Logger) *Server {
+//	    return &Server{log: logger.Named("server")}
+//	}
 //
-//	    logger.Info("application started", ion.F("version", "1.0.0"))
+//	func (s *Server) Start(ctx context.Context) {
+//	    s.log.Info(ctx, "server started", ion.Int("port", 8080))
 //	}
 //
-// # Context Support
+// # Context-First Logging
 //
-// Use FromContext or WithContext to automatically attach trace identifiers:
+// Context is always the first parameter. Trace IDs are extracted automatically:
 //
 //	func HandleRequest(ctx context.Context) {
-//	    // Extracts trace_id and span_id if present in ctx
-//	    logger.WithContext(ctx).Info("processing request", ion.F("user_id", 123))
+//	    // trace_id and span_id are added to logs if present in ctx
+//	    logger.Info(ctx, "processing request")
 //	}
+//
+// For startup and shutdown logs where no trace context exists:
+//
+//	ion.Info(context.Background(), "service starting")
+//
+// # Configuration
+//
+// Ion supports configuration via code or environment variables:
+//
+//	cfg := ion.Default()
+//	cfg.Level = "debug"
+//	cfg.OTEL.Enabled = true
+//	cfg.OTEL.Endpoint = "otel-collector:4317"
+//
+//	logger := ion.New(cfg)
+//
+// Environment variables supported by [InitFromEnv]:
+//
+//	LOG_LEVEL        - debug, info, warn, error (default: info)
+//	LOG_DEVELOPMENT  - "true" for pretty console output
+//	SERVICE_NAME     - service name for logs and OTEL
+//	SERVICE_VERSION  - service version for OTEL resources
+//	OTEL_ENDPOINT    - collector address, enables OTEL if set
+//	OTEL_INSECURE    - "true" to disable TLS
+//	OTEL_USERNAME    - Basic Auth username
+//	OTEL_PASSWORD    - Basic Auth password
+//
+// [Zap]: https://github.com/uber-go/zap
+// [OpenTelemetry]: https://opentelemetry.io/
 package ion

doc.go

@@ -0,0 +1,98 @@
+# Ion Performance Optimization Notes
+
+This document captures performance analysis and trade-off decisions for future reference.
+
+---
+
+## Context Field Slice Pooling (Considered, Not Implemented)
+
+**Date**: 2025-12-22  
+**Status**: Deferred  
+
+### Problem
+
+The `extractContextZapFields` function allocates a new slice on every log call:
+
+```go
+func extractContextZapFields(ctx context.Context) []zap.Field {
+    fields := make([]zap.Field, 0, 4)  // 96 bytes per call
+    // ...
+}
+```
+
+### Proposed Solution
+
+Add a `sync.Pool` for the context field slice:
+
+```go
+var contextFieldPool = sync.Pool{
+    New: func() any {
+        s := make([]zap.Field, 0, 4)
+        return &s
+    },
+}
+
+func extractContextZapFieldsPooled(ctx context.Context) (*[]zap.Field, bool) {
+    ptr := contextFieldPool.Get().(*[]zap.Field)
+    *ptr = (*ptr)[:0]
+    // ... populate
+    return ptr, true  // Caller must return to pool
+}
+```
+
+### Cost/Benefit Analysis
+
+| Factor | Cost | Benefit |
+|--------|------|---------|
+| **Latency** | ~5ns pool overhead | Saves ~50ns allocation |
+| **Memory** | Pool keeps slices alive | Less GC pressure under load |
+| **Complexity** | Medium - caller must return to pool | Zero-alloc hot path |
+| **Risk** | Pool misuse → memory leaks | — |
+| **LOC** | +20 lines | — |
+
+### Decision: Defer
+
+**Rationale**:
+1. The slice is only 96 bytes (4 fields × 24 bytes/field)
+2. Pool Get/Put overhead may negate savings for low-volume logging
+3. Added complexity and leak risk outweigh marginal gains
+4. Alternative optimization (skip for `context.Background()`) provides better ROI
+
+### Future Reconsideration
+
+Revisit if:
+- Benchmarks show >10M logs/sec sustained load
+- Memory profiling shows GC pressure from context slices
+- Users report allocation-related performance issues
+
+---
+
+## Background Context Short-Circuit (Implemented)
+
+**Date**: 2025-12-22  
+**Status**: ✅ Implemented  
+
+### Problem
+
+Every log call runs context extraction, even for `context.Background()` which can never have trace info.
+
+### Solution
+
+Short-circuit the extraction:
+
+```go
+var contextZapFields []zap.Field
+if ctx != nil && ctx != context.Background() && ctx != context.TODO() {
+    contextZapFields = extractContextZapFields(ctx)
+}
+```
+
+### Cost/Benefit
+
+| Factor | Value |
+|--------|-------|
+| **Cost** | 2 pointer comparisons (~1ns) |
+| **Benefit** | Saves 1 allocation for startup/background logs |
+| **Risk** | None - pointer comparison is safe |
+
+**Decision: Implement** — Clear win with minimal cost.

docs/PERFORMANCE_NOTES.md

@@ -55,7 +55,7 @@ Post this announcement to your engineering Slack/Teams channel:
 > We have published `ion`, our new enterprise-grade structured logger tailored for JupiterMeta's blockchain services.
 >
 > **Why use it?**
-> *   🚀 **Zero-Allocation**: Optimized for high-throughput hot paths.
+> *   🚀 **Low-Allocation**: Pool-optimized for high-throughput hot paths.
 > *   🔭 **OTEL Native**: Automatic trace propagation and export.
 > *   🛡️ **Safe**: Graceful shutdown and resource management.
 >