pry

package module
v1.4.3 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 8 Imported by: 18

README

pry

Structured logger for Go. pry itself is the facade — a Logger, a Record and the options that build one — and a driver renders that record. Side channels (Sentry / Glitchtip) receive the same record as a Sink.

zerolog is the default driver and log/slog is the other one. Only pry/zerolog imports zerolog, so a binary that takes the slog driver never links it.

Installation

go get gitlab.com/gorib/pry

Usage

Creating a logger
import (
    "gitlab.com/gorib/pry"
    pryzerolog "gitlab.com/gorib/pry/zerolog"
)

level, err := pry.ParseLevel("info")
if err != nil {
    return err
}
l := pry.New(level, pryzerolog.New(pryzerolog.Plain()))

Levels are trace, debug, info, warn, error. The logger's gate runs before the record is built — a suppressed call costs ~2.6ns and allocates nothing.

Drivers
pryzerolog.New(pryzerolog.Plain())   // console, colour when stdout is a TTY
pryzerolog.New(pryzerolog.Json())    // stdout as JSON
pryslog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: pryslog.LevelTrace}))

The zerolog driver is opened at trace, so the logger's level is the only gate. A slog handler keeps its own level — Info when HandlerOptions.Level is unset — and the stricter of the two wins, so open it at pryslog.LevelTrace to let the logger decide alone.

Writing one is a method:

type Driver interface {
    Log(Record)
}

A driver with something to release implements io.Closer and closing the logger calls it. Measured on an M2 Max, per emitted line:

message + 2 fields + a failure error
pry/zerolog 181 ns · 2 allocs 305 ns · 4 allocs 685 ns · 11 allocs
pry/slog 303 ns · 2 allocs 445 ns · 4 allocs 1891 ns · 15 allocs

zerolog is the default because of that last column; slog exists so a service that wants the standard library is not forced off the rest of the package.

The two write different keys

Both emit JSON — pryzerolog.Json() and slog.NewJSONHandler — but not the same JSON:

pry/zerolog pry/slog + JSONHandler
timestamp time, or @timestamp after Json() time
message message msg
level info INFO

Swapping the driver therefore compiles, runs, and keeps writing lines your log pipeline may stop parsing — a failure you find in an incident rather than in a build. slog.HandlerOptions.ReplaceAttr renames all three when you need the zerolog spelling; there is no helper for it here, because which spelling is right depends on what reads the logs.

Logging

Each method accepts a message and zero or more options:

l.Info("server started")
l.Warn("retrying", pry.Field("attempt", 3))
l.Error(err)                                    // error as message
l.Error("request failed", pry.Err(err))         // string message + error
Method Level zerolog slog
Trace LevelTrace TraceLevel LevelDebug - 4
Debug LevelDebug DebugLevel LevelDebug
Info LevelInfo InfoLevel LevelInfo
Warn LevelWarn WarnLevel LevelWarn
Error LevelError ErrorLevel LevelError

A logger can travel in the context:

ctx = pry.ContextWithLogger(ctx, l)
pry.LoggerFromContext(ctx).Info("started") // pry.Noop() when the context holds none
Options

Options are applied per log call:

Option Description
pry.Err(err) Attaches an error to the event.
pry.Field(key, value) Adds a structured key/value field.
pry.Ctx(ctx) Attaches request context (session metadata). See Session context.
Logger options
Option Description
pry.ToSinks(s...) Adds side channels (e.g., Sentry).

Output format and caller belong to the driver, not the logger:

Option Description
pryzerolog.Plain() Console writer. Colour is dropped when stdout is not a TTY.
pryzerolog.Json() Stdout as JSON. Sets zerolog.TimestampFieldName globally, which affects every zerolog logger in the process.
pryzerolog.WithCaller() Adds caller file and line to every event.

Sinks

A sink receives every record the logger emits, off the calling goroutine.

type Sink interface {
    Write(Record)
    Close() error
}
l := pry.New(level, pryzerolog.New(pryzerolog.Plain()), pry.ToSinks(sentry))
// ...
_ = l.Close() // drain every sink before shutdown

A sink sees only what the logger emits: the level gate runs first, so a sink cannot ask for records below the logger's own level.

It can ask for less, by answering the optional half of the interface:

type Leveled interface {
    Level() Level
}

A record below that level is never sent, so the queue carries only what the sink would keep — channels.Sentry("error") under LOGLEVEL=trace otherwise queues every request the service serves in order to discard each one on arrival. What a sink declines is not counted as dropped: it was never wanted.

The direction is one-way on purpose. A sink that could ask for more than the logger emits would be a second place deciding the level, and then neither LOGLEVEL nor the sink answers "what is written" on its own.

One goroutine per sink, and a queue in front of it

Each sink gets a goroutine and a buffered channel, and Write is called from that goroutine alone. Two things follow, and both are the point:

Records arrive in order. A goroutine per record cannot promise that, and the arrangement that preceded this one started one per record per sink.

A slow sink costs records, not the process. The send never blocks — logging must not become a source of latency — so a full queue drops the record and counts it. Dropped() reads the count, and Close writes a line through the driver when it is not zero, because a drop nobody is told about is the one failure this design has. It is not an error: a shutdown that panicked over a lost log line would be worse than the lost line.

Measured on an M2 Max, the fan-out alone:

per record
a goroutine per record 327 ns, 1 alloc
a send to one goroutine 11 ns, 0 allocs

The queue is what bounds a slow sink. Without it the records became goroutines, and the only limit was memory.

Sentry / Glitchtip
import "gitlab.com/gorib/pry/channels"

sentry, err := channels.Sentry("error",
    channels.WithSentryConnection(dsn, "production",
        channels.WithSentryService("my-service"),
    ),
)

l := pry.New(pry.LevelDebug, pryzerolog.New(pryzerolog.Plain()), pry.ToSinks(sentry))

Sentry(level, ...) — only events at or above level are forwarded to Sentry.

WithSentryConnection(dsn, env, opts...) — configures the Sentry client. If dsn is empty the channel is created but silently does nothing.

WithSentryService(name) — sets ServerName in the Sentry client options.

WithSentryRelease(release) — sets Release.

WithSentryScrubber(fn) — runs fn as BeforeSend on every event; the event it returns is sent, and nil drops it.

When an error is a failure.Error, the Sentry event includes the structured stack trace and type code from failure. Any other error goes through failure.Parse as the sink writes it, so its stack is captured on the sink's goroutine, not at the call site.

Session context

pry.Ctx(ctx) enriches the Sentry event with HTTP request metadata extracted from the session stored in the context:

l.Error("payment failed", pry.Err(err), pry.Ctx(ctx))

The following fields are forwarded to Sentry when present:

Session field Sentry field
CorrelationId tags["correlation_id"]
Uri request.url
Method request.method, tags["method"]
Body request.data
UserAgent request.headers["User-Agent"]
UserLanguage request.headers["Accept-Language"]
SourceIp user.ip_address

request is set when Uri or Method is non-empty. If the context carries no session, none of these are set. The trace context is read from the context rather than the session, so trace_id and the Sentry propagation context are still attached to a session-less record.

Closing

Close and Dropped are not Logger methods — call them on what New returned:

l := pry.New(pry.LevelInfo, pryzerolog.New(pryzerolog.Plain()), pry.ToSinks(sentry))
defer func() { _ = l.Close() }()

It blocks until the in-flight sink writes finish, then closes each sink (Sentry flushes with a 3-second timeout) and the driver, if the driver is an io.Closer.

Testing

pry.Recorder() returns a Logger that keeps what it is given:

rec := pry.Recorder()
svc := newService(rec) // takes a pry.Logger

svc.Pay(ctx, order)

errs := rec.At(pry.LevelError)
errs[0].Field("order") // a pry.Field the code attached: value, found

It is a driver under the real logger, so the options are applied by the code production runs and a test asserts on records the production code built. Entries() returns every record, At(level) those of one level, Reset() clears them. The recorder is open at trace.

pry.Noop() discards everything; use it for a test that asserts nothing about logging.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrLevel = failure.New("unknown log level")

Functions

func ContextWithLogger

func ContextWithLogger(ctx context.Context, l Logger) context.Context

func New

func New(level Level, driver Driver, options ...LoggerOption) *logger

New builds a logger over a driver. The caller parses the level, with ParseLevel.

Types

type Attr added in v1.4.0

type Attr struct {
	Key   string
	Value any
}

Named Attr because Field is the option that appends one.

type Driver added in v1.4.0

type Driver interface {
	Log(Record)
}

Driver renders a record. The level gate, the fan-out to sinks and Close are the logger's.

A driver holding something to release implements io.Closer, and Logger.Close calls it.

type Entry deprecated

type Entry = Record

Deprecated: Entry is Record. Kept so a suite that named the type still builds.

type Level

type Level int8

Ordered so a sink can filter with a comparison. The zero value is LevelDebug.

const (
	LevelTrace Level = iota - 1
	LevelDebug
	LevelInfo
	LevelWarn
	LevelError
)

func ParseLevel added in v1.4.0

func ParseLevel(name string) (Level, error)

func (Level) String added in v1.4.0

func (l Level) String() string

type Leveled added in v1.4.0

type Leveled interface {
	Level() Level
}

Leveled is the optional half of Sink: a sink that answers it is sent nothing below that level, so its queue carries only what it would keep.

It narrows and never widens. A sink that could ask for more than the logger emits would be a second place deciding the level.

type LogRecorder

type LogRecorder struct {
	Logger
	// contains filtered or unexported fields
}

func Recorder

func Recorder() *LogRecorder

Recorder is a Logger that keeps what it was told, for a test that asserts on logging. It is a Driver under the real logger, so options are applied by the code production runs.

func (*LogRecorder) At

func (r *LogRecorder) At(level Level) []Record

func (*LogRecorder) Entries

func (r *LogRecorder) Entries() []Record

func (*LogRecorder) Log added in v1.4.0

func (r *LogRecorder) Log(record Record)

func (*LogRecorder) Reset

func (r *LogRecorder) Reset()

type Logger

type Logger interface {
	Trace(message any, opts ...Option)
	Debug(message any, opts ...Option)
	Info(message any, opts ...Option)
	Warn(message any, opts ...Option)
	Error(message any, opts ...Option)
}

func LoggerFromContext

func LoggerFromContext(ctx context.Context) Logger

func Noop

func Noop() Logger

type LoggerOption

type LoggerOption func(l *logger)

func ToSinks added in v1.4.0

func ToSinks(sinks ...Sink) LoggerOption

ToSinks attaches side channels — Sentry and anything else that receives every record. Output format and caller belong to the driver.

type Option

type Option func(r *Record)

func Ctx

func Ctx(ctx context.Context) Option

func Err

func Err(err error) Option

func Field

func Field(key string, value any) Option

type Record added in v1.4.0

type Record struct {
	Level   Level
	Message string
	Err     error
	Attrs   []Attr

	// Ctx is for a driver that needs it — slog.Handler.Handle takes one.
	Ctx context.Context
	// A copy, because a sink reads it from another goroutine.
	Session *session.Session
}

Record is what a driver renders and a sink forwards — options write it, so a driver outside this package can read everything they set.

func (Record) Field added in v1.4.0

func (r Record) Field(key string) (any, bool)

type Sink added in v1.4.0

type Sink interface {
	Write(Record)
	Close() error
}

Sink receives every record the logger emits, off the calling goroutine.

Directories

Path Synopsis
internal
w3c
Package slog renders pry records through a log/slog handler.
Package slog renders pry records through a log/slog handler.
Package zerolog renders pry records with rs/zerolog.
Package zerolog renders pry records with rs/zerolog.

Jump to

Keyboard shortcuts

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