Files
skills/public/hanzo-log.md

5.1 KiB

Hanzo Log - Structured Logging for Go

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-cli.md, hanzo/hanzo-orm.md

Overview

Hanzo Log is a high-performance, zero-allocation structured logging library for Go. Based on zerolog with a dual API: a zero-allocation chaining style and a geth-compatible variadic style. Both share the same underlying Event system backed by sync.Pool. The standard logging library for all Hanzo Go services.

Why Hanzo Log?

  • Zero allocation: ~8 ns/op for empty log, 0 B/op via sync.Pool event recycling
  • Dual API: Method chaining (zerolog-style) and variadic key-value (geth-style)
  • Logger interface: All logging goes through a Logger interface, enabling Noop/test/custom loggers
  • slog integration: Maps to log/slog levels for stdlib interop
  • Colorized console: Pretty ConsoleWriter with ANSI colors for development
  • Sampling: BasicSampler to throttle high-volume logs in production
  • Hooks: Attach arbitrary processing to log events
  • Lumberjack rotation: Built-in log file rotation via lumberjack.v2

Tech Stack

  • Language: Go 1.26+
  • Module: github.com/hanzoai/log
  • Dependencies: go-colorable, go-isatty, lumberjack.v2 (all minimal)
  • OSS Base: zerolog architecture with geth API layer added
  • CI: GitHub Actions (ci.yml, release.yml, docs.yml)

Repo: github.com/hanzoai/log

When to use

  • Any Hanzo Go service that needs structured logging
  • Replacing go-ethereum/log in Lux/EVM codebases (geth API is compatible)
  • High-throughput services where allocation matters
  • When you need both JSON and human-readable log output

Quick reference

Item Value
Module github.com/hanzoai/log
Repo github.com/hanzoai/log
Go version 1.26+
Install go get github.com/hanzoai/log
License See LICENSE
Sub-packages github.com/hanzoai/log/level

Installation

go get github.com/hanzoai/log

Usage

Chaining API (zero-allocation)

import "github.com/hanzoai/log"

// Simple
log.Info().Msg("hello world")

// With fields
log.Info().
 Str("user", "alice").
 Int("attempt", 3).
 Msg("login successful")

// With timestamp
l := log.NewWriter(os.Stdout).With().Timestamp().Logger()
l.Info().Str("service", "api").Msg("started")

Variadic API (geth-compatible)

import "github.com/hanzoai/log"

// Simple
logger := log.New("component", "myapp")
logger.Info("hello world")

// With fields
logger.Info("login successful",
 log.String("user", "alice"),
 log.Int("attempt", 3),
)

// Error with key
logger.Error("operation failed", log.Err(err))

Logger Interface

All logging goes through the Logger interface:

type Logger interface {
 Trace(msg string, ctx ...interface{})
 Debug(msg string, ctx ...interface{})
 Info(msg string, ctx ...interface{})
 Warn(msg string, ctx ...interface{})
 Error(msg string, ctx ...interface{})
 Fatal(msg string, ctx ...interface{})
 Panic(msg string, ctx ...interface{})
 With() Context
 New(ctx ...interface{}) Logger
 Level(lvl Level) Logger
 // ... plus chaining methods (TraceEvent, DebugEvent, etc.)
}

// Disabled logger for optional params
logger := log.Noop()

Console Output

output := log.ConsoleWriter{Out: os.Stdout}
l := log.NewWriter(output)
l.Info().Str("foo", "bar").Msg("Hello World")
// Output: 3:04pm INF Hello World foo=bar

Log Levels

log.SetGlobalLevel(log.WarnLevel)

// Levels: TraceLevel(-1), DebugLevel(0), InfoLevel(1),
// WarnLevel(2), ErrorLevel(3), FatalLevel(4), PanicLevel(5)

EVM/VM Initialization

logger, err := log.InitLogger("C-chain", "info", false, writer)

Key Files

File Purpose
log.go Logger interface, constructors, core implementation
event.go Event type with sync.Pool recycling
geth.go Geth-compatible Field constructors (String, Int, Err, etc.)
fields.go Internal field encoding for variadic API
globals.go Global config (field names, time formats, colors)
console.go ConsoleWriter for human-readable output
context.go Context builder for pre-set fields
slog.go log/slog handler integration
sampler.go Log sampling (BasicSampler)
encoder_json.go JSON encoder
hook.go Hook interface

Performance

BenchmarkLogEmpty-10 161M ops 8.4 ns/op 0 B/op 0 allocs/op
BenchmarkLogFields-10 32M ops 40.2 ns/op 0 B/op 0 allocs/op
BenchmarkLogFieldType/Str 95M ops 11.7 ns/op 0 B/op 0 allocs/op

Compared to: zerolog (19 ns), zap (236 ns), logrus (1244 ns, 27 allocs).

Field Constructors (geth-style)

log.String(key, val) log.Int(key, val) log.Bool(key, val)
log.Float64(key, val) log.Duration(key, val) log.Time(key, val)
log.Err(err) log.Any(key, val) log.Binary(key, val)
log.Strings(key, vals) log.Ints(key, vals) log.Uint64(key, val)
  • hanzo/hanzo-orm.md - ORM that uses hanzo/log
  • hanzo/hanzo-cli.md - CLI tools
  • hanzo/go-sdk.md - Go SDK

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: logging, go, structured-logging, zerolog, geth, performance Prerequisites: Go 1.26+