ion

Ion

Ion is an enterprise-grade observability client for Go services. It unifies structured logging (Zap), distributed tracing, and metrics (OpenTelemetry) into a single, cohesive API designed for high-throughput, long-running infrastructure.

Status: v0.3 — Pre-release (API stable, targeting v1.0) Target: Microservices, Blockchain Nodes, Distributed Systems

Guarantees & Design Invariants

Ion is built on strict operational guarantees. Operators can rely on these invariants in production:

1. No Process Termination: Ion will never call os.Exit, panic, or log.Fatal. Even Critical level logs are strictly informational (mapped to FATAL severity) and guarantee control flow returns to the caller.
2. Thread Safety: All public APIs on Logger, Tracer, and Meter are safe for concurrent use by multiple goroutines.
3. Non-Blocking Telemetry: Trace and metrics export is asynchronous and decoupled from application logic. A slow OTEL collector will never block your business logic. Logs are synchronous to properly handle crash reporting, but rely on high-performance buffered writes.
4. Failure Isolation: Telemetry backend failures (e.g., Collector down) are isolated. They may result in data loss (dropped spans) but will never crash the service.

Non-Goals

To maintain focus and stability, Ion explicitly avoids:

• 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.

Installation

go get github.com/JupiterMetaLabs/ion

Requires Go 1.24+.

Quick Start

A minimal, correct example for a production service.

package main

import (
    "context"
    "log"
    "time"

    "github.com/JupiterMetaLabs/ion"
)

func main() {
    ctx := context.Background()

    // 1. Initialize with Service Identity
    app, warnings, err := ion.New(ion.Default().WithService("payment-node"))
    if err != nil {
        log.Fatalf("Fatal: failed to init observability: %v", err)
    }
    for _, w := range warnings {
        log.Printf("Ion Startup Warning: %v", w)
    }

    // 2. Establish the Lifecycle Contract — flush before exit
    defer func() {
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        if err := app.Shutdown(shutdownCtx); err != nil {
            log.Printf("Shutdown data loss: %v", err)
        }
    }()

    // 3. Application Logic
    app.Info(ctx, "node started", ion.String("version", "1.0.0"))
    doWork(ctx, app)
}

func doWork(ctx context.Context, logger ion.Logger) {
    logger.Info(ctx, "processing block", ion.Uint64("height", 100))
}

Scoped Observability

Create scoped children that retain full access to logging, tracing, and metrics. This is the recommended pattern for structuring observability in multi-component applications.

app, _, _ := ion.New(cfg)

// Child() returns *Ion with full capabilities
http := app.Child("http")
http.Info(ctx, "request received")

// Full tracing access — no type assertion needed
tracer := http.Tracer("http.handler")
ctx, span := tracer.Start(ctx, "HandleRequest")
defer span.End()

// Full metrics access
meter := http.Meter("http.metrics")
counter, _ := meter.Int64Counter("http.requests.total")
counter.Add(ctx, 1)

Named() and With() also preserve observability (the concrete type behind the Logger interface is *Ion), but Child() returns *Ion directly — no type assertion required. Use Child() when your component needs tracing or metrics. Use Named()/With() when passing through the Logger interface (e.g., across package boundaries).

Developer Reference

Core Types

Creating Children

All three preserve full observability. The difference is the return type — Child() gives you *Ion directly, while Named()/With() return Logger (backed by *Ion internally).

Field Constructors

Ion provides typed field constructors for zero-allocation structured logging:

For blockchain-specific fields, see fields package.

Context Helpers

Ion extracts trace correlation from context.Context automatically. You can also inject custom identifiers:

Log Levels

Levels can be changed at runtime via SetLevel("debug"). Changes propagate to all children sharing the same atomic level.

API Overview

1. The Logger

Use the Logger for human-readable events, state changes, and errors. Always pass context.Context — even context.Background() — to maintain the API contract and enable future trace correlation.

// INFO: Operational state changes
app.Info(ctx, "transaction processed",
    ion.String("tx_id", "0x123"),
    ion.Duration("latency", 50*time.Millisecond),
)

// ERROR: Actionable failures. Does not interrupt flow.
if err != nil {
    app.Error(ctx, "database connection failed", err, ion.String("db_host", "primary"))
}

// CRITICAL: Invariant violations (e.g. data corruption).
// GUARANTEE: Does NOT call os.Exit(). Safe to use in libraries.
app.Critical(ctx, "memory corruption detected", nil)

2. Child Loggers (Scopes)

Use Child, Named, and With to create context-aware sub-loggers. Prefer Child() when the component needs tracing or metrics.

// Child: Full observability — logging, tracing, metrics
http := app.Child("http", ion.String("version", "v2"))
tracer := http.Tracer("http.handler")
meter := http.Meter("http.metrics")

// Named: Logger interface — good for cross-package boundaries
httpLog := app.Named("http")   // {"logger": "app.http", ...}
grpcLog := app.Named("grpc")   // {"logger": "app.grpc", ...}

// With: Permanent fields on all subsequent logs
userLogger := app.With(
    ion.Int("user_id", 42),
    ion.String("tenant", "acme-corp"),
)
userLogger.Info(ctx, "action taken")  // {"user_id": 42, "tenant": "acme-corp", ...}

3. The Tracer

Use the Tracer for latency measurement and causal chains. Every Start must have a corresponding End().

func ProcessOrder(ctx context.Context, orderID string) error {
    tracer := app.Tracer("order.processor")
    ctx, span := tracer.Start(ctx, "ProcessOrder")
    defer span.End()

    span.SetAttributes(attribute.String("order.id", orderID))

    if err := validate(ctx); err != nil {
        span.RecordError(err)
        span.SetStatus(ion.StatusError, "validation failed")
        return err
    }
    return nil
}

Ion provides StatusOK, StatusError, and StatusUnset constants so you don't need to import go.opentelemetry.io/otel/codes. For span attributes, ion.Attr is an alias for attribute.KeyValue — import go.opentelemetry.io/otel/attribute to create attribute values.

4. The Meter

Use Meter for operational metrics (counters, histograms, gauges).

meter := app.Meter("http.metrics")
requestCounter, _ := meter.Int64Counter("http_requests_total")
latencyHist, _ := meter.Float64Histogram("http_request_duration_seconds")

requestCounter.Add(ctx, 1)
latencyHist.Record(ctx, 0.025) // 25ms

5. Blockchain Fields

The fields sub-package provides domain-specific constructors with consistent key naming:

import "github.com/JupiterMetaLabs/ion/fields"

app.Info(ctx, "transaction routed",
    fields.TxHash("0xabc123..."),
    fields.ShardID(3),
    fields.Slot(150_000_000),
    fields.Epoch(350),
    fields.BlockHeight(19_500_000),
    fields.LatencyMs(12.5),
)

Categories: Transaction (TxHash, TxType, Nonce, GasUsed, ...), Block & Consensus (BlockHeight, Slot, Epoch, Validator, ...), Network (ChainID, PeerID, NodeID, ...), and Metrics (Count, Size, LatencyMs, ...).

Configuration Reference

Ion uses a comprehensive configuration struct for behavior control. This maps 1:1 with ion.Config.

Root Configuration (ion.Config)

Console Configuration (ion.ConsoleConfig)

File Configuration (ion.FileConfig)

OTEL Configuration (ion.OTELConfig)

Controls the OpenTelemetry Logs Exporter. Tracing and Metrics inherit Endpoint, Protocol, and auth fields from OTEL when their own values are empty.

Tracing Configuration (ion.TracingConfig)

Controls the OpenTelemetry Trace Provider. Empty fields inherit from OTELConfig.

Metrics Configuration (ion.MetricsConfig)

Controls the OpenTelemetry Metrics Provider (OTLP Push). Empty fields inherit from OTELConfig.

Config Builders

For quick setup, use the fluent builder methods:

// Production: Console + OTEL + Tracing on a shared collector
cfg := ion.Default().
    WithService("order-service").
    WithOTEL("otel-collector:4317").
    WithTracing("").  // inherits OTEL endpoint
    WithMetrics("")   // inherits OTEL endpoint

// Development: Pretty console, debug level, sample all traces
cfg := ion.Development().WithService("order-service")

For full control, initialize the struct directly. See examples/basic/main.go Example 6 for a complete production configuration.

Initialization Recipes

Console Only (CLI / Scripts)

cfg := ion.Default()
cfg.Level = "info"
// cfg.Development = true  // Optional: enables caller info + stack traces

Console + File (VM / Bare Metal)

cfg := ion.Default()
cfg.File.Enabled = true
cfg.File.Path = "/var/log/app/app.log"
cfg.File.MaxSizeMB = 500
cfg.File.MaxBackups = 5

OTEL Only (High-Traffic Sidecars)

cfg := ion.Default()
cfg.Console.Enabled = false
cfg.OTEL.Enabled = true
cfg.OTEL.Endpoint = "localhost:4317"
cfg.OTEL.Protocol = "grpc"

Systemd Native (Journald)

cfg := ion.Default()
cfg.Console.Format = "systemd"
cfg.Console.ErrorsToStderr = true

Full Stack (Kubernetes)

cfg := ion.Default()
cfg.Console.Enabled = true
cfg.OTEL.Enabled = true
cfg.OTEL.Endpoint = "otel-collector:4317"
cfg.Tracing.Enabled = true
cfg.Tracing.Sampler = "ratio:0.1"
cfg.Metrics.Enabled = true

Tracing Guide

Distributed tracing requires discipline. For a complete step-by-step guide to span creation, error handling, background goroutines, and best practices, see the Tracing Quickstart.

HTTP & gRPC Integration

Ion provides middleware and interceptors for automatic context propagation.

HTTP Middleware

import "github.com/JupiterMetaLabs/ion/middleware/ionhttp"

mux := http.NewServeMux()
handler := ionhttp.Handler(mux, "payment-api")
http.ListenAndServe(":8080", handler)

gRPC Interceptors

import "github.com/JupiterMetaLabs/ion/middleware/iongrpc"

// Server
s := grpc.NewServer(grpc.StatsHandler(iongrpc.ServerHandler()))

// Client
conn, _ := grpc.Dial(addr, grpc.WithStatsHandler(iongrpc.ClientHandler()))

Examples

The examples/ directory contains runnable demonstrations:

Best Practices

Context propagation. Always pass context.Context to log methods. Using context.Background() breaks the trace chain — reserve it for main() and background worker roots.

Shutdown is mandatory. Failing to call Shutdown() guarantees data loss for buffered traces, metrics, and OTEL logs. Always defer shutdown in main() with a timeout context.

Use typed fields. Prefer ion.String("key", val) over ion.F("key", val). Typed constructors are zero-allocation and catch type errors at compile time.

Use static keys. ion.String(userInput, "value") is a security risk and breaks log indexing. Keys must be compile-time constants.

Use consistent key naming. Stick to snake_case (e.g., user_id, not userID or uid). The fields package enforces this for blockchain-specific keys.

Prefer Child() for components. When a struct needs logging, tracing, and metrics, accept *ion.Ion and create children with Child(). Use the Logger interface at package boundaries where only logging is needed.

Only shut down the root. Child instances share providers with the parent. Calling Shutdown() on a child tears down shared resources. Shut down only the root *Ion returned by New().

Handle warnings. New() returns warnings for non-fatal issues (e.g., OTEL connection failure). Log these at startup so operators know when telemetry is degraded.

Operational Model

How Ion Works

• Logs: Emitted synchronously to configured cores (Console/File/OTEL). If your application crashes immediately after a log statement, the log is persisted (up to OS buffering).
• Traces: Buffered and exported asynchronously. Spans are batched in memory and sent to the OTEL endpoint on a timer or size threshold.
• Metrics: Pushed asynchronously via OTLP at the configured interval (default 15s).
• Correlation: trace_id and span_id are extracted from context.Context at the moment of logging.

Production Failure Modes

• OTEL Collector Down: Exporter retries with exponential backoff. If buffers fill, new spans/logs are dropped. Application performance is preserved.
• Disk Full (File Logging): Lumberjack rotation attempts to write. If the syscall fails, the application continues but file logs are lost.
• High Load: Tracing and metrics use bounded buffers. Under extreme load, excess data is dropped to prevent memory leaks.

Further Reading

• Observability Reference Specification — Backend engineering invariants, tiered recommendations, OTel Collector configurations.
• Enterprise User Guide — Advanced patterns, DI strategies, and blockchain-specific examples.
• Tracing Quickstart — Step-by-step guide to setting up distributed tracing.

Versioning

• Public API: ion.go, logger.go, config.go, fields.go, tracer.go, attrs.go, context.go. Stable since v0.3.
• Internal: internal/*. No stability guarantees.
• Behavior: Log format changes or configuration defaults are considered breaking changes.

License

MIT © 2025 JupiterMeta Labs