seilog

seilog

Structured logging with per-logger runtime level control, built on log/slog.

seilog was created to provide a uniform logging configuration experience across artifacts produced by Sei. Nothing in the library is Sei-specific — it is a general-purpose slog extension that any Go project can use.

Why seilog?

The standard library's slog gives you structured logging and pluggable handlers, but it lacks two things that matter in production:

1. Per-logger level control. slog has a single global level. When you're debugging a database issue in production, you want DEBUG on your db package without drowning in noise from every other subsystem.

2. Runtime level changes. Restarting a process to flip a log level is slow and disruptive. seilog lets you change levels on the fly — via code, an admin endpoint, or a signal handler — with immediate effect across all goroutines.

seilog adds both while staying out of your way: NewLogger returns a plain *slog.Logger. There is no wrapper type, no custom interface, and no lock-in. Your code uses the standard slog API everywhere.

Features

• Hierarchical logger names — "myapp/db/pool" mirrors your package structure and enables targeted level changes.
• Runtime level control — change levels per logger, by glob pattern, or recursively across an entire subtree without restarting.
• Zero-alloc hot path — the enabled-level check is a single atomic load; disabled log calls cost ~5 ns.
• Standard *slog.Logger return type — no wrapper, no lock-in, full compatibility with the slog ecosystem.
• Strict naming validation — enforced at creation time to prevent typos, injection, and naming inconsistencies across a large codebase.
• Environment-variable configuration — format, output destination, and default level are set once at startup with no code changes.
• Concurrent safety — all functions are safe for concurrent use. Level changes are atomic and visible immediately.

Quick start

package main

import (
    "log/slog"
    "github.com/sei-protocol/seilog"
)

// Create loggers at package level — they're cheap and reusable.
var log = seilog.NewLogger("myapp", "db")

func main() {
    defer seilog.Close()

    log.Info("connected", "host", "localhost", "port", 5432)

    // Turn on debug for the db subtree at runtime.
    seilog.SetLevel("myapp/db/**", slog.LevelDebug)

    log.Debug("query plan", "sql", "SELECT ...")
}

Logger naming

Logger names form a /-separated hierarchy. Use the variadic form of NewLogger to build them — each segment is validated individually:

seilog.NewLogger("myapp")               // "myapp"
seilog.NewLogger("myapp", "db")         // "myapp/db"
seilog.NewLogger("myapp", "db", "pool") // "myapp/db/pool"

Each segment must match [a-z0-9]+(-[a-z0-9]+)* (lowercase alphanumerics and hyphens). This is enforced via panic at creation time.

The lowercase-only rule is a deliberate tradeoff — what matters most is consistency. In a multi-team codebase, if one package registers "MyApp" and another uses "myapp", they silently create separate registry entries and SetLevel on one won't affect the other. Rather than trusting convention, the library enforces a single canonical form. Lowercase was chosen because it's the most common Go naming convention for identifiers in packages and paths, but any uniform rule would serve the same purpose.

The broader constraints (no whitespace, no special characters) exist for additional reasons:

Setting levels

Levels can be changed at any time without restarting the process:

// Exact match
seilog.SetLevel("myapp/db", slog.LevelDebug)

// Glob — direct children only (path.Match semantics, * doesn't cross /)
seilog.SetLevel("myapp/*", slog.LevelDebug)

// Glob — grandchildren only
seilog.SetLevel("myapp/*/*", slog.LevelWarn)

// Recursive — myapp and ALL descendants at any depth
seilog.SetLevel("myapp/**", slog.LevelDebug)

// Everything
seilog.SetLevel("*", slog.LevelWarn)

SetLevel returns the number of loggers matched, which helps catch typos:

if n := seilog.SetLevel("myap/db", slog.LevelDebug); n == 0 {
    fmt.Println("typo? no loggers matched")
}

Querying levels

lvl, ok := seilog.GetLevel("myapp/db")
if ok {
    fmt.Printf("myapp/db is at %s\n", lvl)
}

// List all registered loggers.
for _, name := range seilog.ListLoggers() {
    lvl, _ := seilog.GetLevel(name)
    fmt.Printf("  %-30s %s\n", name, lvl)
}

Environment variables

Output format, destination, and default level are configured at startup via environment variables. These are read once during package init and cannot be changed afterward.

When SEI_LOG_OUTPUT is a file path:

• The path must be absolute and must not contain .. components.
• Files are opened with mode 0600 and O_APPEND for atomic POSIX writes.
• seilog does not perform log rotation — use an external tool like logrotate.
• Call seilog.Close() during graceful shutdown to flush and close the file descriptor.

API

func NewLogger(name string, subs ...string) *slog.Logger
func SetLevel(name string, level slog.Level) int
func GetLevel(name string) (slog.Level, bool)
func SetDefaultLevel(level slog.Level, updateExisting bool)
func ListLoggers() []string
func Close() error

Full documentation: pkg.go.dev/github.com/sei-protocol/seilog

Performance

seilog's goal is to add per-logger level control with negligible overhead compared to using slog directly. Benchmarks on Apple M2 Max (arm64), comparing seilog against stdlib slog with the same JSONHandler writing to io.Discard:

Key takeaways:

• Zero allocations on every hot path. seilog adds no allocations beyond what slog itself performs.
• Disabled-level calls are ~5 ns — a single atomic load short-circuits before touching the handler. This is 15% faster than stdlib because seilog's LevelVar check avoids the handler dispatch entirely.
• Enabled-level overhead is 2–3% across all scenarios (Info, typed attrs, pre-bound attrs, text handler, parallel). This is within benchmark noise — seilog is effectively free at log time.
• Contention under concurrent SetLevel mutations adds modest overhead (~325 ns/op) with no lock contention surprises — the RWMutex + atomic LevelVar design holds up cleanly.

go test -bench=. -benchmem ./...

Best practices

Logger creation

Create loggers as package-level variables. This is cheap (one registry lookup after the first call), keeps names consistent, and avoids passing loggers through function arguments:

// db/db.go
var log = seilog.NewLogger("myapp", "db")

// db/pool.go
var poolLog = seilog.NewLogger("myapp", "db", "pool")

Avoid creating loggers inside functions or request handlers — it adds unnecessary registry lookups on every call and makes it harder to discover which loggers exist.

Message style

Log messages should be short, static strings that describe what happened. Put variable data in attributes, not in the message itself:

// Good — message is static, data is structured and searchable.
log.Info("Query executed", "sql", query, "duration-ms", elapsed.Milliseconds(), "rows", count)

// Bad — message changes every time, impossible to group or filter.
log.Info(fmt.Sprintf("query %s took %dms and returned %d rows", query, elapsed.Milliseconds(), count))

Whether you capitalize the first letter ("Query executed") or keep it all lowercase ("query executed") doesn't matter — what matters is that your codebase picks one convention and sticks with it. Inconsistent casing makes log search and grouping harder than it needs to be.

Use past tense or noun phrases and skip trailing punctuation: "Connection opened", "Cache miss", "Block committed". Avoid generic messages like "error" or "done" — they're useless when scanning logs.

Attribute keys

Use lowercase kebab-case for consistency: "request-id", "block-height", "duration-ms". Include units in the key name when the value is numeric ("duration-ms", "size-bytes"). Prefer slog.String, slog.Int, and slog.Any over untyped key-value pairs when performance matters — the typed API avoids any boxing.

Level selection

If you find yourself setting Debug on a logger and leaving it on permanently, the messages are probably Info. If Warn messages never lead to action, they're noise — demote them to Debug or remove them.

Error logging

Log errors at the point where you handle them, not at every level of the call stack. If you return an error, don't also log it — the caller will decide:

// Good — log once at the handling site.
if err := db.Exec(ctx, query); err != nil {
    log.Error("Query failed", "sql", query, "err", err)
    return fmt.Errorf("execute query: %w", err)
}

// Bad — logs the same error at every layer.

Use "err" as the conventional key for error values.

Contextual attributes

Use .With() to attach request-scoped data once rather than repeating it on every log call:

func handleRequest(w http.ResponseWriter, r *http.Request) {
    reqLog := log.With("request-id", r.Header.Get("X-Request-ID"), "method", r.Method)
    reqLog.Info("Request started", "path", r.URL.Path)
    // ... all subsequent logs carry request-id and method.
    reqLog.Info("Request completed", "status", 200)
}

Naming hierarchy

Mirror your module or package structure. A consistent convention makes SetLevel patterns predictable across teams:

myapp
myapp/db
myapp/db/pool
myapp/api
myapp/api/middleware
myapp/indexer

This way myapp/db/** always means "the database layer and everything in it" and myapp/api/* means "direct children of the API layer" — no guesswork.

Design choices

License

Apache License v2.