feat: add OpenTelemetry Metrics support and remove global accessors

BREAKING CHANGES:
- Removed SetGlobal, GetGlobal, and global helper functions
- Users must use instance methods (app.Info, app.Tracer, app.Meter)
Features:
- Add ion.MetricsConfig for OTel Metrics (OTLP Push)
- Add app.Meter(name) method for creating instruments
- Add enterprise-grade defaults (ratio:0.1 sampling, 15s metrics interval)
- Add Metrics example in examples/basic/
Docs:
- Updated README with Metrics configuration reference
- Updated doc.go package description

Author: i-naman

.gitignore

@@ -1,2 +1,8 @@
 .DS_Store
 ion-release/
+
+# Compiled Go binaries (named after directory)
+/basic
+examples/basic/basic
+examples/otel-test/otel-test
+*.exe

README.md

@@ -19,7 +19,6 @@ Ion is built on strict operational guarantees. Operators can rely on these invar
 ## Non-Goals
 
 To maintain focus and stability, Ion explicitly avoids:
-*   **Metrics**: Use the Prometheus or OpenTelemetry Metrics SDKs directly.
 *   **Alerting**: Ion emits signals; it does not manage thresholds or paging.
 *   **Framework Magic**: Ion does not auto-inject into HTTP handlers without explicit middleware usage.
 
@@ -116,6 +115,7 @@ Ion uses a comprehensive configuration struct for behavior control. This maps 1:
 | `File` | `FileConfig` | `Enabled: false` | configuration for file logging (with rotation). |
 | `OTEL` | `OTELConfig` | `Enabled: false` | configuration for remote OpenTelemetry logging. |
 | `Tracing` | `TracingConfig` | `Enabled: false` | configuration for Distributed Tracing. |
+| `Metrics` | `MetricsConfig` | `Enabled: false` | configuration for OpenTelemetry Metrics. |
 
 ### Console Configuration (`ion.ConsoleConfig`)
 | Field | Type | Default | Description |
@@ -157,11 +157,24 @@ Controls the OpenTelemetry **Trace** Provider.
 |-------|------|---------|-------------|
 | `Enabled` | `bool` | `false` | Enables trace generation and export. |
 | `Endpoint` | `string` | `""` | `host:port`. **Inherits** `OTEL.Endpoint` if empty. |
-| `Sampler` | `string` | `"always"` | `"always"`, `"never"`, or `"ratio:0.X"` (e.g., `ratio:0.1` for 10%). |
+| `Sampler` | `string` | `"ratio:0.1"` | `"always"`, `"never"`, or `"ratio:0.X"` (e.g., `ratio:0.1` for 10%). Development mode uses `"always"`. |
 | `Protocol` | `string` | `"grpc"` | `"grpc"` or `"http"`. **Inherits** `OTEL.Protocol` if empty. |
 | `Username` | `string` | `""` | **Inherits** `OTEL.Username` if empty. |
 | `Password` | `string` | `""` | **Inherits** `OTEL.Password` if empty. |
 
+### Metrics Configuration (`ion.MetricsConfig`)
+Controls the OpenTelemetry **Metrics** Provider (OTLP Push).
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `Enabled` | `bool` | `false` | Enables metrics export. |
+| `Endpoint` | `string` | `""` | `host:port`. **Inherits** `OTEL.Endpoint` if empty. |
+| `Interval` | `Duration` | `15s` | Push interval. Development mode uses `5s`. |
+| `Temporality` | `string` | `"cumulative"` | `"cumulative"` (Prometheus-compatible) or `"delta"`. |
+| `Protocol` | `string` | `"grpc"` | **Inherits** `OTEL.Protocol` if empty. |
+| `Username` | `string` | `""` | **Inherits** `OTEL.Username` if empty. |
+| `Password` | `string` | `""` | **Inherits** `OTEL.Password` if empty. |
+
 ---
 
 ## Detailed Initialization
@@ -482,27 +495,6 @@ Operators must understand how Ion behaves under stress:
 
 ---
 
-## Globals & Dependency Injection
-
-> **⚠️ WARNING**: Global state is strictly for migration and legacy support.
-
-**Do not** use `ion.SetGlobal` in new libraries or microservices.
-**Do** inject `ion.Logger` via struct constructors.
-
-```go
-// CORRECT: Dependency Injection
-type Server struct {
-    log ion.Logger
-}
-
-// INCORRECT: Hidden dependency
-func (s *Server) Handle() {
-    ion.Info(...) // Relies on global state
-}
-```
-
-If `ion.GetGlobal()` is called without initialization, it returns a **safe no-op logger**. It will not panic, but your logs will be silently discarded to protect the runtime.
-
 ---
 
 ## Best Practices

config.go

@@ -20,6 +20,9 @@ type OTELConfig = config.OTELConfig
 // TracingConfig configures distributed tracing.
 type TracingConfig = config.TracingConfig
 
+// MetricsConfig configures OpenTelemetry metrics export.
+type MetricsConfig = config.MetricsConfig
+
 // Default returns a Config with sensible production defaults.
 func Default() Config {
 	return config.Default()

doc.go

@@ -1,21 +1,21 @@
-// Package ion provides production-grade logging and tracing for Go services.
+// Package ion provides production-grade logging, tracing, and metrics for Go services.
 //
-// Ion unifies structured logging (Zap) and distributed tracing
+// Ion unifies structured logging (Zap), distributed tracing, and metrics
 // (OpenTelemetry) behind a minimal, context-first API.
 //
 // # Guarantees
 //
 //   - Process Safety: Ion never terminates the process (no os.Exit, no panic).
-//   - Concurrency: All Logger and Tracer APIs are safe for concurrent use.
+//   - Concurrency: All Logger, Tracer, and Meter APIs are safe for concurrent use.
 //   - Failure Isolation: Telemetry backend failures never crash application logic.
 //   - Lifecycle: Shutdown(ctx) flushes all buffers on a best-effort basis.
 //
 // # Architecture
 //
 //   - Logs: Synchronous, structured, strongly typed.
 //   - Traces: Asynchronous, sampled, batched.
+//   - Metrics: Asynchronous, pushed via OTLP.
 //   - Correlation: Automatic injection of trace_id/span_id from context.Context.
 //
 // Ion is designed for long-running services and distributed systems.
-// It is not a metrics SDK or a web framework.
 package ion

docs/USER_GUIDE.md

@@ -156,12 +156,12 @@ In a blockchain node, distinct subsystems (P2P, Consensus, Mempool) need distinc
 
 ```go
 // main.go (Node Entrypoint)
-root := ion.New(cfg) // name="ion-node"
+app, _, _ := ion.New(cfg) // name="ion-node"
 
 // Inject scoped loggers into major components
-p2pServer := p2p.NewServer(root.Named("p2p"))        // name="ion-node.p2p"
-consensus := engine.New(root.Named("consensus"))     // name="ion-node.consensus"
-mempool   := pool.New(root.Named("mempool"))         // name="ion-node.mempool"
+p2pServer := p2p.NewServer(app.Named("p2p"))        // name="ion-node.p2p"
+consensus := engine.New(app.Named("consensus"))     // name="ion-node.consensus"
+mempool   := pool.New(app.Named("mempool"))         // name="ion-node.mempool"
 ```
 
 ```go

examples/basic/main.go

@@ -96,26 +96,38 @@ func example3_ChildLoggers() {
 }
 
 // ============================================================================
-// Example 4: Global Usage Pattern
-// For scripts or legacy code where DI is impractical.
+// Example 4: Metrics
+// Demonstrates OpenTelemetry metrics instrumentation.
 // ============================================================================
 
-func example4_GlobalUsage() {
+func example4_Metrics() {
 	ctx := context.Background()
 
-	app, _, _ := ion.New(ion.Default().WithService("script"))
-	ion.SetGlobal(app)
-	defer ion.Sync()
+	cfg := ion.Default().WithService("metrics-demo")
+	cfg.Metrics.Enabled = true
+	cfg.Metrics.Endpoint = "localhost:4317" // OTel Collector
+	cfg.Metrics.Protocol = "grpc"
+	cfg.Metrics.Insecure = true
 
-	// Now use package-level functions anywhere
-	ion.Info(ctx, "using global logger")
-	ion.Debug(ctx, "debug from anywhere")
+	app, _, err := ion.New(cfg)
+	if err != nil {
+		log.Fatalf("Failed to create ion: %v", err)
+	}
+	defer app.Shutdown(ctx)
+
+	// Get a named meter
+	meter := app.Meter("example.metrics")
 
-	// Get tracer from global too
-	tracer := ion.GetTracer("script.process")
-	ctx, span := tracer.Start(ctx, "DoWork")
-	ion.Info(ctx, "inside span") // Has trace_id, span_id
-	span.End()
+	// Create instruments
+	requestCounter, _ := meter.Int64Counter("http_requests_total") // metric.WithDescription("Total HTTP requests"),
+
+	latencyHist, _ := meter.Float64Histogram("http_request_duration_seconds") // metric.WithDescription("HTTP request latency"),
+
+	// Record metrics
+	requestCounter.Add(ctx, 1)
+	latencyHist.Record(ctx, 0.025) // 25ms
+
+	app.Info(ctx, "metrics recorded")
 }
 
 // ============================================================================
@@ -189,9 +201,6 @@ func example6_ProductionSetup() {
 		log.Printf("ion warning: %v", w)
 	}
 
-	// Set as global for convenience
-	ion.SetGlobal(app)
-
 	// CRITICAL: Graceful shutdown to flush all logs and traces
 	defer func() {
 		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
@@ -251,8 +260,8 @@ func main() {
 	fmt.Println("\n=== Example 3: Child Loggers ===")
 	example3_ChildLoggers()
 
-	fmt.Println("\n=== Example 4: Global Usage ===")
-	example4_GlobalUsage()
+	fmt.Println("\n=== Example 4: Metrics ===")
+	example4_Metrics()
 
 	fmt.Println("\n=== Example 5: Blockchain Fields ===")
 	example5_BlockchainFields()

go.mod

@@ -9,11 +9,15 @@ require (
 	go.opentelemetry.io/otel v1.39.0
 	go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.15.0
 	go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp v0.15.0
+	go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.39.0
+	go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp v1.39.0
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.39.0
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.39.0
 	go.opentelemetry.io/otel/log v0.15.0
+	go.opentelemetry.io/otel/metric v1.39.0
 	go.opentelemetry.io/otel/sdk v1.39.0
 	go.opentelemetry.io/otel/sdk/log v0.15.0
+	go.opentelemetry.io/otel/sdk/metric v1.39.0
 	go.opentelemetry.io/otel/trace v1.39.0
 	go.uber.org/zap v1.27.1
 	google.golang.org/grpc v1.77.0
@@ -30,7 +34,6 @@ require (
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.39.0 // indirect
-	go.opentelemetry.io/otel/metric v1.39.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.9.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	golang.org/x/net v0.47.0 // indirect

go.sum

@@ -37,6 +37,10 @@ go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.15.0 h1:W+m0g+/6v
 go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.15.0/go.mod h1:JM31r0GGZ/GU94mX8hN4D8v6e40aFlUECSQ48HaLgHM=
 go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp v0.15.0 h1:EKpiGphOYq3CYnIe2eX9ftUkyU+Y8Dtte8OaWyHJ4+I=
 go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp v0.15.0/go.mod h1:nWFP7C+T8TygkTjJ7mAyEaFaE7wNfms3nV/vexZ6qt0=
+go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.39.0 h1:cEf8jF6WbuGQWUVcqgyWtTR0kOOAWY1DYZ+UhvdmQPw=
+go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.39.0/go.mod h1:k1lzV5n5U3HkGvTCJHraTAGJ7MqsgL1wrGwTj1Isfiw=
+go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp v1.39.0 h1:nKP4Z2ejtHn3yShBb+2KawiXgpn8In5cT7aO2wXuOTE=
+go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp v1.39.0/go.mod h1:NwjeBbNigsO4Aj9WgM0C+cKIrxsZUaRmZUO7A8I7u8o=
 go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.39.0 h1:f0cb2XPmrqn4XMy9PNliTgRKJgS5WcL/u0/WRYGz4t0=
 go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.39.0/go.mod h1:vnakAaFckOMiMtOIhFI2MNH4FYrZzXCYxmb1LlhoGz8=
 go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.39.0 h1:in9O8ESIOlwJAEGTkkf34DesGRAc/Pn8qJ7k3r/42LM=

internal/config/config.go

@@ -39,6 +39,9 @@ type Config struct {
 
 	// Tracing configuration for distributed tracing.
 	Tracing TracingConfig `yaml:"tracing" json:"tracing"`
+
+	// Metrics configuration for OpenTelemetry metrics.
+	Metrics MetricsConfig `yaml:"metrics" json:"metrics"`
 }
 
 // ConsoleConfig configures console (stdout/stderr) output.
@@ -174,7 +177,48 @@ type TracingConfig struct {
 	Attributes map[string]string `yaml:"attributes" json:"attributes"`
 }
 
+// MetricsConfig configures OpenTelemetry metrics export.
+type MetricsConfig struct {
+	// Enabled controls whether metrics export is active.
+	Enabled bool `yaml:"enabled" json:"enabled"`
+
+	// Protocol: "grpc" or "http".
+	Protocol string `yaml:"protocol" json:"protocol"`
+
+	// Endpoint is the OTEL collector endpoint for metrics.
+	// Falls back to OTEL.Endpoint if not set.
+	Endpoint string `yaml:"endpoint" json:"endpoint"`
+
+	// Insecure disables TLS.
+	Insecure bool `yaml:"insecure" json:"insecure"`
+
+	// Username for Basic Authentication (optional).
+	Username string `yaml:"username" json:"username" env:"METRICS_USERNAME"`
+
+	// Password for Basic Authentication (optional).
+	Password string `yaml:"password" json:"password" env:"METRICS_PASSWORD"`
+
+	// Headers for authentication.
+	Headers map[string]string `yaml:"headers" json:"headers"`
+
+	// Timeout for export.
+	Timeout time.Duration `yaml:"timeout" json:"timeout"`
+
+	// Interval is the push interval for metrics.
+	// Default: 15s
+	Interval time.Duration `yaml:"interval" json:"interval"`
+
+	// Temporality preference: "cumulative" (default) or "delta".
+	// Prometheus prefers Cumulative.
+	Temporality string `yaml:"temporality" json:"temporality"`
+
+	// Attributes for metrics resource.
+	Attributes map[string]string `yaml:"attributes" json:"attributes"`
+}
+
 // Default returns a Config with sensible production defaults.
+// All telemetry backends (OTEL, Tracing, Metrics) are disabled by default.
+// When enabled, they inherit endpoint/auth from OTEL config automatically.
 func Default() Config {
 	return Config{
 		Level:       "info",
@@ -201,15 +245,46 @@ func Default() Config {
 			BatchSize:      512,
 			ExportInterval: 5 * time.Second,
 		},
+		Tracing: TracingConfig{
+			Enabled:        false,
+			Sampler:        "ratio:0.1", // 10% sampling for production (safe default)
+			BatchSize:      512,
+			ExportInterval: 5 * time.Second,
+			// Endpoint, Protocol, Auth inherited from OTEL if empty
+		},
+		Metrics: MetricsConfig{
+			Enabled:     false,
+			Interval:    15 * time.Second, // Standard OTel push interval
+			Temporality: "cumulative",     // Prometheus-compatible
+			// Endpoint, Protocol, Auth inherited from OTEL if empty
+		},
 	}
 }
 
 // Development returns a Config optimized for development.
+//   - Debug level logging with pretty console output.
+//   - Tracing pre-configured with "always" sampling (but disabled by default).
+//   - Metrics pre-configured with 5s push interval (but disabled by default).
+//
+// To enable observability, you must explicitly set:
+//
+//	cfg.OTEL.Enabled = true           // For remote log export
+//	cfg.OTEL.Endpoint = "localhost:4317"
+//	cfg.OTEL.Insecure = true          // For local dev
+//	cfg.Tracing.Enabled = true        // For distributed tracing
+//	cfg.Metrics.Enabled = true        // For metrics export
 func Development() Config {
 	cfg := Default()
 	cfg.Level = "debug"
 	cfg.Development = true
 	cfg.Console.Format = "pretty"
+
+	// Dev-friendly tracing: sample everything
+	cfg.Tracing.Sampler = "always"
+
+	// Dev-friendly metrics: faster feedback loop
+	cfg.Metrics.Interval = 5 * time.Second
+
 	return cfg
 }
 
@@ -248,6 +323,15 @@ func (c Config) WithTracing(endpoint string) Config {
 	return c
 }
 
+// WithMetrics returns a copy of the config with metrics enabled.
+func (c Config) WithMetrics(endpoint string) Config {
+	c.Metrics.Enabled = true
+	if endpoint != "" {
+		c.Metrics.Endpoint = endpoint
+	}
+	return c
+}
+
 // NewFileWriter creates a log file writer with rotation.
 func NewFileWriter(cfg FileConfig) io.Writer {
 	return &lumberjack.Logger{
@@ -307,6 +391,19 @@ func (c Config) Validate() error {
 		errs = append(errs, fmt.Sprintf("invalid tracing protocol %q (use: grpc, http)", c.Tracing.Protocol))
 	}
 
+	// Validate metrics config
+	if c.Metrics.Enabled {
+		if c.Metrics.Endpoint == "" && c.OTEL.Endpoint == "" {
+			errs = append(errs, "metrics enabled but no endpoint (set Metrics.Endpoint or OTEL.Endpoint)")
+		}
+		if c.Metrics.Protocol != "" && c.Metrics.Protocol != "grpc" && c.Metrics.Protocol != "http" {
+			errs = append(errs, fmt.Sprintf("invalid metrics protocol %q (use: grpc, http)", c.Metrics.Protocol))
+		}
+		if c.Metrics.Temporality != "" && c.Metrics.Temporality != "cumulative" && c.Metrics.Temporality != "delta" {
+			errs = append(errs, fmt.Sprintf("invalid metrics temporality %q (use: cumulative, delta)", c.Metrics.Temporality))
+		}
+	}
+
 	if len(errs) > 0 {
 		return fmt.Errorf("config validation failed: %s", strings.Join(errs, "; "))
 	}