slogbox

func (*Handler) All ¶

func (h *Handler) All() iter.Seq[slog.Record]

All returns an iterator over stored records from oldest to newest. The snapshot is taken under a read lock; the iteration itself holds no lock. If MaxAge is set, records older than MaxAge are excluded.

package main

import (
	"fmt"
	"log/slog"

	"github.com/alexrios/slogbox"
)

func main() {
	h := slogbox.New(10, nil)
	logger := slog.New(h)

	logger.Info("alpha")
	logger.Info("beta")

	for r := range h.All() {
		fmt.Println(r.Message)
	}
}

Output:

alpha
beta

func (*Handler) Capacity ¶

func (h *Handler) Capacity() int

Capacity returns the total buffer capacity (the size passed to New).

func (*Handler) Clear ¶

func (h *Handler) Clear()

Clear removes all records from the buffer and resets flush state. It does not wait for any in-flight flush: a concurrent Handle that has already claimed its flush window will still deliver those records to FlushTo after Clear returns. New records written after Clear form a fresh window.

func (*Handler) Enabled ¶

func (h *Handler) Enabled(_ context.Context, level slog.Level) bool

Enabled reports whether the handler stores records at the given level.

func (*Handler) Flush ¶

func (h *Handler) Flush(ctx context.Context) error

Flush explicitly drains pending records to [Options.FlushTo]. It is intended for graceful shutdown sequences where buffered records would otherwise be lost.

Flush only requires [Options.FlushTo] to be set; [Options.FlushOn] is not needed. This allows a manual-only flush pattern where records are never flushed automatically but can be drained on demand.

Flush is a no-op (returns nil) when FlushTo is not configured, when the buffer is empty, or when all records have already been flushed.

The flush window is claimed under the write lock before delivery begins (same at-most-once semantics as Handler.Handle). The provided context is passed to each FlushTo.Handle call; ctx.Err() is checked between records to support early cancellation.

On error (from FlushTo or context cancellation), Flush returns immediately. Records delivered before the error are not retried; records not yet delivered are lost because the flush window was already claimed.

package main

import (
	"context"
	"fmt"
	"io"
	"log/slog"
	"time"

	"github.com/alexrios/slogbox"
)

func main() {
	target := slog.NewJSONHandler(io.Discard, nil)
	h := slogbox.New(100, &slogbox.Options{
		FlushTo: target,
	})
	logger := slog.New(h)

	logger.Info("buffered event")

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	if err := h.Flush(ctx); err != nil {
		fmt.Println("flush error:", err)
	}
	fmt.Println("pending after flush:", h.PendingFlushCount())
}

Output:

pending after flush: 0

func (*Handler) Handle ¶

func (h *Handler) Handle(_ context.Context, r slog.Record) error

Handle stores a clone of r in the ring buffer. If FlushOn/FlushTo are configured and the record's level reaches the FlushOn threshold, all records since the last flush are forwarded to FlushTo. If FlushTo.Handle returns an error, Handle returns that error to the caller. The flush window is claimed before flushing begins (at-most-once semantics), so claimed records are never re-sent even when an error is returned.

func (*Handler) JSON ¶

func (h *Handler) JSON() ([]byte, error)

JSON returns the buffered records as a JSON array suitable for HTTP responses. If MaxAge is set, records older than MaxAge are excluded.

package main

import (
	"fmt"
	"log/slog"

	"github.com/alexrios/slogbox"
)

func main() {
	h := slogbox.New(10, &slogbox.Options{Level: slog.LevelError})
	logger := slog.New(h)

	logger.Info("ignored") // below Error level
	logger.Error("failure", "code", 500)

	data, err := h.JSON()
	if err != nil {
		panic(err)
	}
	fmt.Println(h.Len())
	fmt.Println(len(data) > 0)
}

Output:

1
true

func (*Handler) Len ¶

func (h *Handler) Len() int

Len returns the number of records physically stored in the buffer. It does not apply MaxAge filtering.

func (*Handler) PendingFlushCount ¶

func (h *Handler) PendingFlushCount() int

PendingFlushCount returns the number of records that would be flushed by Handler.Flush or the next level-triggered flush. Returns 0 if [Options.FlushTo] is not set.

func (*Handler) Records ¶

func (h *Handler) Records() []slog.Record

Records returns a snapshot of stored records from oldest to newest. If MaxAge is set, records older than MaxAge are excluded.

package main

import (
	"fmt"
	"log/slog"

	"github.com/alexrios/slogbox"
)

func main() {
	h := slogbox.New(10, nil)
	logger := slog.New(h)

	logger.Info("first")
	logger.Info("second")

	for _, r := range h.Records() {
		fmt.Println(r.Message)
	}
}

Output:

first
second

func (*Handler) RecordsAbove ¶

func (h *Handler) RecordsAbove(minLevel slog.Level) []slog.Record

RecordsAbove returns a snapshot of stored records whose level is >= minLevel, from oldest to newest. If MaxAge is set, old records are excluded before level filtering. The semantics match Handler.Enabled: a record is included when its level reaches or exceeds minLevel.

func (*Handler) TotalRecords ¶

func (h *Handler) TotalRecords() uint64

TotalRecords returns the total number of records ever written to the buffer. The counter is monotonically increasing and survives wrap-around; it is only reset by Handler.Clear.

func (*Handler) WithAttrs ¶

func (h *Handler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a new Handler whose records will include the given attrs. The new handler shares the same ring buffer.

func (*Handler) WithGroup ¶

func (h *Handler) WithGroup(name string) slog.Handler

WithGroup returns a new Handler that qualifies later attrs with the given group name. The new handler shares the same ring buffer.

func (*Handler) WriteTo ¶

func (h *Handler) WriteTo(w io.Writer) (int64, error)

WriteTo writes the buffered records as a JSON array to w. It implements io.WriterTo so it can be passed directly to helpers that accept that interface, and can write directly to an http.ResponseWriter. If MaxAge is set, records older than MaxAge are excluded.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log/slog"

	"github.com/alexrios/slogbox"
)

func main() {
	h := slogbox.New(10, nil)
	logger := slog.New(h)

	logger.Info("first")
	logger.Info("second")

	var buf bytes.Buffer
	if _, err := h.WriteTo(&buf); err != nil {
		panic(err)
	}

	var entries []map[string]any
	if err := json.Unmarshal(buf.Bytes(), &entries); err != nil {
		panic(err)
	}
	for _, e := range entries {
		fmt.Println(e["msg"])
	}
}

Output:

first
second