ion

Ion

Ion is an enterprise-grade, structured logging library designed for high-performance blockchain applications at JupiterMeta Labs.

It combines the raw speed of Zap with seamless OpenTelemetry (OTEL) integration, ensuring your logs are both fast and observable.

Features

• 🚀 High Performance: Built on Uber's Zap with a custom Zero-Allocation core for hot paths.
• 🔭 OpenTelemetry Native: Seamless integration with OTEL for distributed tracing (Logs + Traces).
• 🛡️ Enterprise Grade: Reliable Shutdown hooks, internal pooling, and safe concurrency patterns.
• 🔗 Blockchain Ready: Specialized field helpers for TxHash, Slot, ShardID, and more.
• 📝 Developer Friendly: Pretty console output for local dev, JSON for production.
• 🔄 Lumberjack: Built-in file rotation and compression.

Installation

go get github.com/JupiterMetaLabs/ion

Quick Start

Basic Usage

package main

import (
	"github.com/JupiterMetaLabs/ion"
)

func main() {
	// Initialize with default settings
	logger := ion.New(ion.Default())
	defer logger.Sync()

	logger.Info("service started", ion.F("port", 8080))
}

With Context (Tracing)

Ion automatically correlates logs with distributed traces if a context is provided.

func HandleRequest(ctx context.Context) {
    // If ctx contains OTEL trace info, it will be added to the log
    logger.WithContext(ctx).Info("processing transaction",
        ion.F("user_id", "u_12345"),
    )
}

Configuration

Ion uses a strongly typed Config struct. You can load it from code or environment variables.

cfg := ion.Default()

// Override with env vars or manual settings
cfg.Level = "debug"
cfg.ServiceName = "payment-service"
cfg.OTEL.Enabled = true
cfg.OTEL.Endpoint = "otel-collector:4317"

logger := ion.New(cfg)

Production Configuration

For enterprise deployments, you should utilize the full configuration power (Files, Rotation, OTEL):

cfg := ion.Config{
    Level:       "info",
    Development: false,      // JSON format
    ServiceName: "payment-service",
    
    // File Logging with Rotation (Lumberjack)
    File: &ion.FileConfig{
        Enabled:    true,
        Path:       "/var/log/app/service.log",
        MaxSize:    100, // MB
        MaxBackups: 10,
        Compress:   true,
    },

    // OpenTelemetry Export
    OTEL: &ion.OTELConfig{
        Enabled:  true,
        Endpoint: "otel-collector:4317", // gRPC by default
        Protocol: "grpc",
        BatchSize: 1000,
        Attributes: map[string]string{
            "env": "production",
        },
    },
}
logger, _ := ion.NewWithOTEL(cfg)
defer logger.Shutdown(ctx)

🏗️ Recommended Usage for Teams

1. Dependency Injection (Preferred)

Pass the ion.Logger explicitly to your components. This makes testing easier and dependencies clear.

type Server struct {
    log ion.Logger
}

func NewServer(l ion.Logger) *Server {
    return &Server{
        log: l.With("component", "server"), // Attach context once
    }
}

2. Global Singleton (Refactoring / Scripts)

For legacy codebases or simple scripts where passing the logger is difficult, use the global singleton.

// In main.go
ion.SetGlobal(logger)

// In package foo
func Bar() {
    // Uses the globally configured logger
    ion.L().Info("something happened")
}

🚀 Performance Tips

Ion is designed for high-performance zero-allocation logging. To maximize speed:

1. Use Typed Constructors: Always use ion.Int, ion.String, ion.Bool instead of ion.F.
   • ion.String("key", "val") -> 0 allocations
   • ion.F("key", "val") -> 1 allocation (boxing to any)

3. Lifecycle & Runtime Configuration

Graceful Shutdown

Always ensure you flush logs before your application exits to prevent data loss (especially for OTEL traces).

// In main()
logger, _ := ion.NewWithOTEL(cfg)
// Use a timeout context to ensure we don't hang if OTEL collector is down
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
defer logger.Shutdown(ctx)

Runtime Configuration (Dynamic Level)

Ion supports changing the log level at runtime without restarting the application. This is thread-safe.

// Safe to call concurrently
logger.SetLevel("debug") 
// Later...
logger.SetLevel("info")

Hot Reloading (Initialization Pattern)

A common pattern for applications is to start with a basic logger, load configuration, and then upgrade to a production logger.

func main() {
    // 1. Start with a safe default (Console, Info)
    ion.SetGlobal(ion.New(ion.Default()))

    // 2. Load Configuration (e.g., from YAML or Env)
    appConfig := LoadConfig()

    // 3. Initialize Production Logger (File, OTEL, etc.)
    prodLogger, err := ion.NewWithOTEL(appConfig.Log)
    if err != nil {
        ion.L().Fatal("failed to init logger", err)
    }

    // 4. Replace Global Logger
    ion.SetGlobal(prodLogger)
    
    // 5. Run App
    RunApp(ion.L())
}

🚀 Performance Tips

Ion is designed for high-performance zero-allocation logging. To maximize speed:

1. Use Typed Constructors: Always use ion.Int, ion.String, ion.Bool instead of ion.F.
   • ion.String("key", "val") -> 0 allocations
   • ion.F("key", "val") -> 1 allocation (boxing to any)
2. Sync vs Shutdown: logger.Sync() only flushes the local buffer. logger.Shutdown(ctx) flushes everything (including OTEL) and closes connections. Use Shutdown on exit.

The Config struct maps to YAML/JSON and Environment Variables.

Architecture

Ion is designed as a wrapper around zap.Logger. It injects a custom Core for OTEL integration that does not impede the performance of local logging.

• Console/File: Handled directly by Zap.
• OTEL: Handled by an asynchronous batch processor to avoid blocking the application.

License

MIT © 2025 JupiterMeta Labs