logring

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package logring captures slog output into an in-memory ring buffer so a developer agent can fetch the records behind a single failed request by its request id ("one artifact per failure").

The handler wraps the logger's regular format handler (see logx.Options.WrapHandler): every record that reaches stdout is also captured here, indexed per request id (read from the request context, see webx.RequestIDFromCtx) with an LRU bound on distinct requests, plus a global tail window. String values are scrubbed through redactx by default so credentials never land in the buffer.

This is a development-observability surface, not a production log sink: it is process-local, bounded, and loses everything on restart. Products that need durable logs should ship stdout to a real aggregator (the JSON format plus request_id correlation keeps that door open).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Wrap

func Wrap(out **Ring, opt Options) func(slog.Handler) slog.Handler

Wrap is the logx.Options.WrapHandler adapter: it builds the capture handler around the format handler that logx constructed, and hands the Ring back through the out parameter so the app can query it.

Types

type Attr

type Attr struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

Attr is one flattened key/value pair of a captured record. Group nesting is flattened to dotted keys, and values are stored as their string representation (post-redaction) so entries stay safely JSON-serializable.

type Entry

type Entry struct {
	Time      time.Time  `json:"time"`
	Level     slog.Level `json:"level"`
	Message   string     `json:"message"`
	RequestID string     `json:"request_id,omitempty"`
	Attrs     []Attr     `json:"attrs,omitempty"`
}

Entry is one captured log record.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler is the capture slog.Handler. Query the backing store via Ring.

func New

func New(next slog.Handler, opt Options) *Handler

New returns a slog.Handler that captures every record it receives into a Ring and forwards them to next (typically the logx format handler). The returned handler's Enabled follows next, so stdout level semantics are unchanged and only records actually emitted are captured.

func (*Handler) Enabled

func (h *Handler) Enabled(ctx context.Context, l slog.Level) bool

func (*Handler) Handle

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

func (*Handler) Ring

func (h *Handler) Ring() *Ring

Ring exposes the queryable store.

func (*Handler) WithAttrs

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

func (*Handler) WithGroup

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

type Options

type Options struct {
	// Capacity is the global tail-window size in records.
	Capacity int
	// PerRequestCapacity bounds the records retained per request id.
	PerRequestCapacity int
	// MaxRequests bounds how many distinct request ids are retained;
	// the least recently used request id is evicted first.
	MaxRequests int
	// Redact controls scrubbing captured strings through redactx.
	// Default (nil) is true.
	Redact *bool
}

Options configures a Ring. Zero values fall back to the defaults above.

type Query

type Query struct {
	// MinLevel drops entries below this level (default: keep everything).
	MinLevel slog.Level
	// Limit caps the result; the newest entries win. 0 means a small
	// default (100).
	Limit int
}

Query filters and bounds a logring read.

type Ring

type Ring struct {
	// contains filtered or unexported fields
}

Ring is the queryable store behind a capture Handler. Create one with New.

func (*Ring) ByRequestID

func (r *Ring) ByRequestID(requestID string, q Query) []Entry

ByRequestID returns the captured entries for one request, oldest first.

func (*Ring) Stats

func (r *Ring) Stats() Stats

Stats returns counters for diagnostics.

func (*Ring) Tail

func (r *Ring) Tail(q Query) []Entry

Tail returns the most recent captured entries across all requests, oldest first. Entries without a request id are included; use ByRequestID for per-request correlation.

type Stats

type Stats struct {
	Captured          uint64 `json:"captured"`
	DroppedGlobal     uint64 `json:"dropped_global"`
	DroppedPerRequest uint64 `json:"dropped_per_request"`
	DroppedRequests   uint64 `json:"dropped_requests"`
	Requests          int    `json:"requests"`
}

Stats is a point-in-time view of the ring for diagnostics.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL