Merge branch 'dev'

# Conflicts:
#	README.md

Author: i-naman

README.md

@@ -1,224 +1,31 @@
 package ion
 
 import (
-	"os"
-	"time"
+	"github.com/JupiterMetaLabs/ion/internal/config"
 )
 
 // Config holds the complete logger configuration.
-type Config struct {
-	// Level sets the minimum log level: debug, info, warn, error.
-	// Default: "info"
-	Level string `yaml:"level" json:"level" env:"LOG_LEVEL"`
+// It is an alias to internal/config.Config to allow sharing with internal packages.
+type Config = config.Config
 
-	// Development enables development mode with:
-	// - Pretty console output by default
-	// - Caller information in logs
-	// - Stack traces on error/fatal
-	Development bool `yaml:"development" json:"development" env:"LOG_DEVELOPMENT"`
+// ConsoleConfig configures console output.
+type ConsoleConfig = config.ConsoleConfig
 
-	// ServiceName identifies this service in logs and OTEL.
-	// Default: "unknown"
-	ServiceName string `yaml:"service_name" json:"service_name" env:"SERVICE_NAME"`
+// FileConfig configures file output.
+type FileConfig = config.FileConfig
 
-	// Version is the application version, included in logs.
-	Version string `yaml:"version" json:"version" env:"SERVICE_VERSION"`
+// OTELConfig configures OTEL log export.
+type OTELConfig = config.OTELConfig
 
-	// Console output configuration.
-	Console ConsoleConfig `yaml:"console" json:"console"`
-
-	// File output configuration (with rotation).
-	File FileConfig `yaml:"file" json:"file"`
-
-	// OTEL (OpenTelemetry) exporter configuration.
-	OTEL OTELConfig `yaml:"otel" json:"otel"`
-}
-
-// ConsoleConfig configures console (stdout/stderr) output.
-type ConsoleConfig struct {
-	// Enabled controls whether console output is active.
-	// Default: true
-	Enabled bool `yaml:"enabled" json:"enabled"`
-
-	// Format: "json" for structured JSON, "pretty" for human-readable.
-	// Default: "json" (production), "pretty" (development)
-	Format string `yaml:"format" json:"format"`
-
-	// Color enables ANSI colors in pretty format.
-	// Default: true
-	Color bool `yaml:"color" json:"color"`
-
-	// ErrorsToStderr sends warn/error/fatal to stderr, others to stdout.
-	// Default: true
-	ErrorsToStderr bool `yaml:"errors_to_stderr" json:"errors_to_stderr"`
-}
-
-// FileConfig configures file output with rotation.
-type FileConfig struct {
-	// Enabled controls whether file output is active.
-	// Default: false
-	Enabled bool `yaml:"enabled" json:"enabled"`
-
-	// Path is the log file path.
-	// Example: "/var/log/app/app.log"
-	Path string `yaml:"path" json:"path"`
-
-	// MaxSizeMB is the maximum size in MB before rotation.
-	// Default: 100
-	MaxSizeMB int `yaml:"max_size_mb" json:"max_size_mb"`
-
-	// MaxAgeDays is the maximum age in days to retain old logs.
-	// Default: 7
-	MaxAgeDays int `yaml:"max_age_days" json:"max_age_days"`
-
-	// MaxBackups is the maximum number of old log files to keep.
-	// Default: 5
-	MaxBackups int `yaml:"max_backups" json:"max_backups"`
-
-	// Compress enables gzip compression of rotated log files.
-	// Default: true
-	Compress bool `yaml:"compress" json:"compress"`
-}
-
-// OTELConfig configures OpenTelemetry log export.
-type OTELConfig struct {
-	// Enabled controls whether OTEL export is active.
-	// Default: false
-	Enabled bool `yaml:"enabled" json:"enabled"`
-
-	// Protocol: "grpc" or "http". gRPC is recommended for performance.
-	// Default: "grpc"
-	Protocol string `yaml:"protocol" json:"protocol"`
-
-	// Endpoint is the OTEL collector endpoint.
-	// Examples: "localhost:4317" (gRPC), "localhost:4318/v1/logs" (HTTP)
-	Endpoint string `yaml:"endpoint" json:"endpoint"`
-
-	// Insecure disables TLS for the connection.
-	// Default: false
-	Insecure bool `yaml:"insecure" json:"insecure"`
-
-	// Username for Basic Authentication (optional).
-	Username string `yaml:"username" json:"username" env:"OTEL_USERNAME"`
-
-	// Password for Basic Authentication (optional).
-	Password string `yaml:"password" json:"password" env:"OTEL_PASSWORD"`
-
-	// Headers are additional headers to send (e.g., auth tokens).
-	Headers map[string]string `yaml:"headers" json:"headers"`
-
-	// Timeout is the export timeout.
-	// Default: 10s
-	Timeout time.Duration `yaml:"timeout" json:"timeout"`
-
-	// BatchSize is the number of logs per export batch.
-	// Default: 512
-	BatchSize int `yaml:"batch_size" json:"batch_size"`
-
-	// ExportInterval is how often to export batched logs.
-	// Default: 5s
-	ExportInterval time.Duration `yaml:"export_interval" json:"export_interval"`
-
-	// Attributes are additional resource attributes for OTEL.
-	// Example: {"environment": "production", "chain": "solana"}
-	Attributes map[string]string `yaml:"attributes" json:"attributes"`
-}
+// TracingConfig configures distributed tracing.
+type TracingConfig = config.TracingConfig
 
 // Default returns a Config with sensible production defaults.
 func Default() Config {
-	return Config{
-		Level:       "info",
-		Development: false,
-		ServiceName: "unknown",
-		Console: ConsoleConfig{
-			Enabled:        true,
-			Format:         "json",
-			Color:          true,
-			ErrorsToStderr: true,
-		},
-		File: FileConfig{
-			Enabled:    false,
-			MaxSizeMB:  100,
-			MaxAgeDays: 7,
-			MaxBackups: 5,
-			Compress:   true,
-		},
-		OTEL: OTELConfig{
-			Enabled:        false,
-			Protocol:       "grpc",
-			Insecure:       false,
-			Timeout:        10 * time.Second,
-			BatchSize:      512,
-			ExportInterval: 5 * time.Second,
-		},
-	}
+	return config.Default()
 }
 
 // Development returns a Config optimized for development.
 func Development() Config {
-	cfg := Default()
-	cfg.Level = "debug"
-	cfg.Development = true
-	cfg.Console.Format = "pretty"
-	return cfg
-}
-
-// WithLevel returns a copy of the config with the specified level.
-func (c Config) WithLevel(level string) Config {
-	c.Level = level
-	return c
-}
-
-// WithService returns a copy of the config with the specified service name.
-func (c Config) WithService(name string) Config {
-	c.ServiceName = name
-	return c
-}
-
-// WithOTEL returns a copy of the config with OTEL enabled.
-func (c Config) WithOTEL(endpoint string) Config {
-	c.OTEL.Enabled = true
-	c.OTEL.Endpoint = endpoint
-	return c
-}
-
-// WithFile returns a copy of the config with file logging enabled.
-func (c Config) WithFile(path string) Config {
-	c.File.Enabled = true
-	c.File.Path = path
-	return c
-}
-
-// InitFromEnv initializes a logger using environment variables.
-// 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
-func InitFromEnv() Logger {
-	cfg := Default()
-
-	if val := os.Getenv("LOG_LEVEL"); val != "" {
-		cfg.Level = val
-	}
-	if val := os.Getenv("SERVICE_NAME"); val != "" {
-		cfg.ServiceName = val
-	}
-	if os.Getenv("LOG_DEVELOPMENT") == "true" {
-		cfg.Development = true
-		cfg.Console.Format = "pretty"
-	}
-	if val := os.Getenv("OTEL_ENDPOINT"); val != "" {
-		cfg.OTEL.Enabled = true
-		cfg.OTEL.Endpoint = val
-	}
-
-	if cfg.OTEL.Enabled && cfg.OTEL.Endpoint != "" {
-		l, err := NewWithOTEL(cfg)
-		if err == nil {
-			return l
-		}
-	}
-
-	return New(cfg)
+	return config.Development()
 }

basic

@@ -1,14 +1,24 @@
+// Package ion context helpers provide functions for propagating trace, request,
+// and user IDs through context.Context. These values are automatically extracted
+// and included in log entries.
+//
+// For OTEL tracing, trace_id and span_id are automatically extracted from the
+// span context. For non-OTEL scenarios, use WithTraceID to set manually.
 package ion
 
 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 +27,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 +58,52 @@ 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).
+// Lazily allocates the slice only when fields are found.
+func extractContextZapFields(ctx context.Context) []zap.Field {
 	if ctx == nil {
 		return nil
 	}
 
-	fields := make([]Field, 0, 4)
+	var fields []zap.Field
 
 	// Extract OTEL trace context (if available)
 	spanCtx := trace.SpanContextFromContext(ctx)
 	if spanCtx.IsValid() {
+		fields = make([]zap.Field, 0, 4)
 		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 = make([]zap.Field, 0, 4)
+			fields = append(fields, zap.String("trace_id", traceID))
 		}
 		if spanID, ok := ctx.Value(spanIDKey).(string); ok && spanID != "" {
-			fields = append(fields, String("span_id", spanID))
+			if fields == nil {
+				fields = make([]zap.Field, 0, 4)
+			}
+			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))
+		if fields == nil {
+			fields = make([]zap.Field, 0, 4)
+		}
+		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))
+		if fields == nil {
+			fields = make([]zap.Field, 0, 4)
+		}
+		fields = append(fields, zap.String("user_id", userID))
 	}
 
 	return fields

config.go

@@ -0,0 +1,50 @@
+version: "3.8"
+
+services:
+  # OpenTelemetry Collector - receives logs and traces from ion
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:latest
+    container_name: ion-otel-collector
+    command: [ "--config=/etc/otel-collector-config.yaml" ]
+    volumes:
+      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml:ro
+    ports:
+      - "4317:4317" # OTLP gRPC
+      - "4318:4318" # OTLP HTTP
+    depends_on:
+      - jaeger
+
+  # Jaeger - trace visualization
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    container_name: ion-jaeger
+    environment:
+      - COLLECTOR_OTLP_ENABLED=true
+    ports:
+      - "16686:16686" # Jaeger UI
+      - "14268:14268" # Jaeger collector HTTP
+
+  # Loki - log aggregation system
+  loki:
+    image: grafana/loki:3.0.0
+    ports:
+      - "3100:3100"
+    command: -config.file=/etc/loki/local-config.yaml
+    volumes:
+      - ./loki-config.yaml:/etc/loki/local-config.yaml
+
+  # Grafana - visualization
+  grafana:
+    image: grafana/grafana:latest
+    ports:
+      - "3001:3000"
+    environment:
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+    volumes:
+      - ./grafana-datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml
+      - ./grafana-dashboards.yaml:/etc/grafana/provisioning/dashboards/dashboards.yaml
+      - ./ion-dashboard.json:/etc/grafana/provisioning/dashboards/imported/ion-dashboard.json
+    depends_on:
+      - loki
+      - jaeger

context.go

@@ -0,0 +1,12 @@
+apiVersion: 1
+
+providers:
+  - name: 'Default'
+    orgId: 1
+    folder: ''
+    type: file
+    disableDeletion: false
+    updateIntervalSeconds: 10
+    allowUiUpdates: true
+    options:
+      path: /etc/grafana/provisioning/dashboards/imported