splinter

Simple and minimal logger in Go for my projects.

Fans out structured records to one or more streams. Ships with a console stream (JSON or pretty text) and a file stream with size- and time-based rotation, optional gzip compression, and backup pruning.

Install

go get git.juancwu.dev/juancwu/splinter@v0.1.0

Requires Go 1.26 or newer.

Quick start

The package exposes a default logger that writes JSON to stderr at LevelInfo:

package main

import "git.juancwu.dev/juancwu/splinter"

func main() {
    splinter.Info("server started", "port", 8080)
    splinter.Error("request failed", "err", "timeout")
}

Custom logger with file output and rotation

package main

import (
    "time"

    "git.juancwu.dev/juancwu/splinter"
)

func main() {
    logger := splinter.New(
        splinter.WithStream(splinter.NewConsoleStream(
            splinter.ConsolePretty, splinter.LevelDebug,
        )),
        splinter.WithStream(splinter.MustFileStream("logs/app.log", splinter.FileStreamConfig{
            Level:      splinter.LevelInfo,
            Format:     splinter.FileJSON,
            MaxSizeMB:  100,              // rotate at 100 MB
            MaxAge:     24 * time.Hour,   // and at least once per day
            MaxBackups: 7,                // keep the 7 most recent files
            Compress:   true,             // gzip rotated backups
        })),
        splinter.WithAttrs(map[string]any{"service": "api"}),
    )
    defer logger.Close()

    splinter.SetDefault(logger)

    splinter.Info("ready")
}

Child loggers

Logger.With returns a child that inherits streams and merges additional attributes onto every record:

req := logger.With(map[string]any{"request_id": id})
req.Info("handled", "status", 200)

Custom streams

Implement the Stream interface to send logs anywhere — a database, a message queue, an HTTP endpoint, an in-memory buffer for tests:

type Stream interface {
    Name() string
    Write(ctx context.Context, rec splinter.Record) error
    Enabled(level splinter.Level) bool
    Close() error
}

Add it with splinter.WithStream(myStream) at construction time.

Configuration reference

`ConsoleStream`

Constructor	Behaviour
`NewConsoleStream(ConsoleJSON, level)`	One JSON object per line on stderr.
`NewConsoleStream(ConsolePretty, level)`	`key=value` text on stderr.
`ConsoleWriter(w)` option	Override the destination writer.

`FileStream`

Field	Default	Notes
`Level`	`LevelInfo`	Minimum level written to the file.
`Format`	`FileJSON`	`FileJSON` or `FileText`.
`MaxSizeMB`	`100`	Rotation threshold in MB. `0` disables size-based rotation.
`MaxAge`	`0`	Rotation threshold by age. `0` disables time-based rotation.
`MaxBackups`	`5`	Number of rotated files to retain (raw + `.gz` combined).
`Compress`	`false`	gzip rotated files asynchronously after rename.

When both MaxSizeMB and MaxAge are zero, MaxSizeMB defaults to 100 to prevent unbounded growth.

License

MIT — see LICENSE.

3.5 KiB Raw Permalink Blame History