slogbox

A slog.Handler that keeps the last N log records in a fixed-size circular buffer. Zero external dependencies -- stdlib only.

Primary use case: exposing recent logs via health-check or admin HTTP endpoints. Inspired by runtime/trace.FlightRecorder, it can also act as a black box recorder that flushes context-rich logs on error.

Install

go get github.com/alexrios/slogbox

Quick start

package main

import (
	"log/slog"
	"net/http"

	"github.com/alexrios/slogbox"
)

func main() {
	rec := slogbox.New(500, nil)
	logger := slog.New(rec)
	slog.SetDefault(logger)

	http.Handle("GET /debug/logs", slogbox.HTTPHandler(rec, nil))

	slog.Info("server starting", "port", 8080)
	http.ListenAndServe(":8080", nil)
}

API overview

| Function / Method | Description | |---|---| | New(size, opts) | Create a handler with buffer capacity size | | Handle(ctx, record) | Store a record (implements slog.Handler); triggers flush if FlushOn threshold is met | | WithAttrs(attrs) | Return a handler with additional attributes (shared buffer) | | WithGroup(name) | Return a handler with a group prefix (shared buffer) | | Records() | Snapshot of stored records, oldest to newest (respects MaxAge) | | RecordsAbove(minLevel) | Snapshot filtered to records >= minLevel (respects MaxAge) | | All() | iter.Seq[slog.Record] iterator over stored records (respects MaxAge) | | JSON() | Marshal records as a JSON array (respects MaxAge) | | WriteTo(w) | Stream records as JSON to an io.Writer (implements io.WriterTo) | | HTTPHandler(h, onErr) | Ready-made http.Handler serving JSON logs; pass nil for default 500 on error | | Flush(ctx) | Explicitly drain pending records to FlushTo (for graceful shutdown) | | Len() | Number of records physically stored (ignores MaxAge) | | Capacity() | Total buffer capacity | | TotalRecords() | Monotonic count of records ever written (survives wrap-around; reset by Clear) | | PendingFlushCount() | Number of records pending for next flush (0 if flush not configured) | | Clear() | Remove all records and reset flush state |

Options

| Field | Type | Description | |---|---|---| | Level | slog.Leveler | Minimum level stored (default: INFO) | | FlushOn | slog.Leveler | Level that triggers flush to FlushTo | | FlushTo | slog.Handler | Destination for flushed records | | MaxAge | time.Duration | Exclude records older than this from reads; 0 = no filter |

Black box pattern

Keep a ring buffer of recent logs and flush them to stderr when an error occurs:

rec := slogbox.New(500, &slogbox.Options{
	FlushOn: slog.LevelError,
	FlushTo: slog.NewJSONHandler(os.Stderr, nil),
	MaxAge:  5 * time.Minute,
})
logger := slog.New(rec)

logger.Info("request started", "path", "/api/users")
logger.Info("db query", "rows", 42)
// ... when an error happens, all recent logs are flushed to stderr
logger.Error("query failed", "err", err)

Serve the ring buffer over HTTP:

http.Handle("GET /debug/logs", slogbox.HTTPHandler(rec, nil))

Or with a custom error handler:

http.Handle("GET /debug/logs", slogbox.HTTPHandler(rec, func(w http.ResponseWriter, r *http.Request, err error) {
	slog.Error("debug/logs: write error", "err", err)
}))

Graceful shutdown

On process exit, records accumulated since the last level-triggered flush are silently lost. Use Flush to drain them:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := rec.Flush(ctx); err != nil {
	log.Printf("flush error: %v", err)
}

Observability

Monitor buffer throughput and pending flush count:

fmt.Printf("total records written: %d\n", rec.TotalRecords())
fmt.Printf("pending flush: %d\n", rec.PendingFlushCount())

Streaming JSON with GOEXPERIMENT=jsonv2

When built with GOEXPERIMENT=jsonv2, WriteTo uses encoding/json/v2's streaming jsontext.Encoder to write records one at a time, avoiding a single large intermediate []byte allocation. The API is identical -- the optimization is transparent.

GOEXPERIMENT=jsonv2 go build ./...
GOEXPERIMENT=jsonv2 go test -bench=BenchmarkWriteTo -benchmem ./...

Without the experiment flag, WriteTo falls back to encoding/json.Marshal (the default behavior).

Benchmarks

Representative values on an Intel Core i9-14900K (32 threads):

| Benchmark | ns/op | B/op | allocs/op | |---|---:|---:|---:| | Handle | 150 | 48 | 1 | | Handle_Parallel | 440 | 48 | 1 | | Handle_WithFlush | 144 | 48 | 1 | | Handle_FlushTrigger (100 records) | 32,900 | 37,568 | 101 | | Flush (100 records) | 33,800 | 37,568 | 101 | | Records (1000) | 138,000 | 294,912 | 1 | | All (1000) | 161,900 | 294,984 | 4 | | JSON (100 records, 5 attrs) | 306,500 | 143,400 | 1,904 | | WriteTo (100 records) | 224,600 | 143,300 | 1,904 | | WriteTo_LargeBuffer (10K records) | 25,700,000 | 16,300,000 | 190,026 | | WithAttrs (5 attrs) | 459 | 496 | 3 | | WithGroup | 38 | 16 | 1 | | Records_WithMaxAge | 198,600 | 294,912 | 1 |

WriteTo with GOEXPERIMENT=jsonv2

When built with the jsonv2 experiment, WriteTo streams records through jsontext.Encoder instead of marshalling the entire array at once:

| Benchmark | default | jsonv2 | improvement | |---|---:|---:|---| | WriteTo (100 records, B/op) | 143,300 | 34,296 | 4x less memory | | WriteTo (100 records, allocs/op) | 1,904 | 35 | 54x fewer allocs | | WriteTo (10K records, ns/op) | 25,700,000 | 960,000 | 27x faster | | WriteTo (10K records, B/op) | 16,300,000 | 2,885,115 | 6x less memory | | WriteTo (10K records, allocs/op) | 190,026 | 35 | 5400x fewer allocs |

Design notes

Building slogbox — design decisions, tradeoffs, and lessons learned.

License

GPL-3.0