author

   █████████   █████  █████ ███████████ █████   █████    ███████    ███████████  
  ███░░░░░███ ░░███  ░░███ ░█░░░███░░░█░░███   ░░███   ███░░░░░███ ░░███░░░░░███ 
 ░███    ░███  ░███   ░███ ░   ░███  ░  ░███    ░███  ███     ░░███ ░███    ░███ 
 ░███████████  ░███   ░███     ░███     ░███████████ ░███      ░███ ░██████████  
 ░███░░░░░███  ░███   ░███     ░███     ░███░░░░░███ ░███      ░███ ░███░░░░░███ 
 ░███    ░███  ░███   ░███     ░███     ░███    ░███ ░░███     ███  ░███    ░███ 
 █████   █████ ░░████████      █████    █████   █████ ░░░███████░   █████   █████
░░░░░   ░░░░░   ░░░░░░░░      ░░░░░    ░░░░░   ░░░░░    ░░░░░░░    ░░░░░   ░░░░░ 
    

Install

go get github.com/0x626f/author

Quick start

logger := author.New(author.Config{
    Level: author.INFO,
})

logger.Info("server started")
// INFO: server started

logger.Info("user %s connected (id=%d)", "alice", 42)
// INFO: user alice connected (id=42)

Config

logger := author.New(author.Config{
    Level:     author.INFO,
    Format:    author.Terminal, // author.Terminal (default) or author.JSON
    Name:      "api",         // adds [api] prefix to every line
    Timestamp: true,          // prepends timestamp to every line
    Out:       os.Stdout,     // defaults to os.Stdout
    Err:       os.Stderr,     // defaults to os.Stderr
})

Log levels

Levels are ordered: FATAL < ERROR < WARNING < INFO < DEBUG < TRACE < NONE. Setting Level suppresses everything above it.

logger.Trace("entering reconcile loop")
logger.Debug("query took %dms", 12)
logger.Info("listening on :%d", 8080)
logger.Warning("retry %d of 3", attempt)
logger.Error("connection refused: %v", err)
logger.Log("raw message without a level") // requires Level=author.NONE

Error writes to Err, everything else writes to Out.

Bound attributes

Calling With on a logger creates and returns a single-use LogRecord. Attributes belong to that record and do not mutate the logger or leak into other records. Record builders are intentionally lock-free: build and finish each record from one goroutine.

record := logger.With("env", "prod").
    With("region", "eu-west-1")

record.Info("server ready")
// INFO: server ready env: prod region: eu-west-1

Calling With on a record returns the same record, enabling fluent chaining. Calling it again with the same key overwrites the previous value on that record. A log method is terminal; do not reuse the record afterward.

Bound records

Use a LogRecord to build the attributes for one log event. Attribute updates append directly without synchronization, and the record proxies its output through the logger it is bound to.

record := logger.Record()
record.With("component", "checkout").
    With("region", "eu-west-1")

record.Info("request accepted")
// INFO: request accepted component: checkout region: eu-west-1

logger.With(...) is shorthand for creating a record and applying the first attribute.

LogRecord and JsonLogRecord instances are backed by separate internal sync.Pools. Calling any log method clears and returns the record to its pool automatically. Do not share an unfinished record between goroutines or use it after a log method. The Logger remains safe for concurrent calls; each goroutine should acquire its own record.

JSON output

Set Format to author.JSON to emit regular log calls as JSON:

logger := author.New(author.Config{
    Level:  author.INFO,
    Format: author.JSON,
})

logger.Info("server started on port %d", 8080)
// {"level":"INFO","message":"server started on port 8080"}

To add typed fields, create a single-use JsonLogRecord with JSON():

record := logger.JSON().
    String("env", "prod").
    Int("port", 8080).
    Bool("tls", true).
    Float64("latency_ms", 142.7)

record.Info("request handled")
// {"env":"prod","port":8080,"tls":true,"latency_ms":142.7,"level":"INFO","message":"request handled"}

The log call clears and internally recycles the record. Create a new JSON record for the next event.

Available field types: String, Byte, Bytes, Bool, Int, Int8, Int16, Int32, Int64, UInt, UInt8, UInt16, UInt32, UInt64, Float32, Float64, StringArray, ByteArray, BoolArray, IntArray (and all numeric array variants).

Nested objects

Implement JSONMarshaller to embed a struct as a nested JSON object.

type User struct{ ID int; Role string }

func (u *User) Marshall(r *author.JsonLogRecord) {
    r.Int("id", u.ID).String("role", u.Role)
}

record := logger.JSON().Object("user", &User{ID: 1, Role: "admin"})
record.Info("access granted")
// {"user":{"id":1,"role":"admin"},"level":"INFO","message":"access granted"}

Attributes in JSON

With attributes appear as fields in the JSON object too.

record := logger.JSON().Int("port", 8080)
record.With("env", "prod").Info("ready")
// {"env":"prod","port":8080,"level":"INFO","message":"ready"}

Context

Store a logger in a context.Context and retrieve it anywhere downstream.

ctx := logger.Ctx(context.Background())

// later, in a handler or downstream function:
author.Ctx(ctx).Info("handling request")

Ctx(ctx) panics if no logger was stored.

To capture selected values from any context chain, pass their keys to WithContextValues:

type contextKey string

const (
    requestIDKey contextKey = "request_id"
    traceIDKey   contextKey = "trace_id"
)

ctx := context.WithValue(context.Background(), requestIDKey, "req-123")
ctx = context.WithValue(ctx, traceIDKey, "trace-456")

record := logger.WithContextValues(ctx, requestIDKey, traceIDKey)
record.Info("handling request")
// INFO: handling request request_id: req-123 trace_id: trace-456

On a logger, WithContextValues creates and returns a new LogRecord. On an existing record, it adds the attributes and returns that same record. It captures the nearest value for each requested key and uses fmt.Sprint(key) as its attribute name. Nil keys and missing values are ignored. Go contexts cannot be enumerated, so every desired key must be requested explicitly. Logger, LogRecord, and JsonLogRecord all implement IAttributeLogger and therefore ILogger.

Parsing log level from config

var cfg struct {
    LogLevel author.LogLevel `env:"LOG_LEVEL"`
}
// also available directly:
level := author.ParseLogLevel("debug") // returns author.DEBUG

Benchmarks

Run the Author benchmarks with:

go test -run '^$' -bench . -benchmem -benchtime=500ms -count=5

Representative medians on Go 1.25.5, Linux/amd64, AMD Ryzen AI 7 350, and GOMAXPROCS=16, writing to io.Discard:

Typed JsonLogRecord fields are the zero-allocation path. Dynamically sourced values passed through the generic With(name, value any) API can incur interface-boxing allocations.