log

README

gotd/log

A minimal, dependency-free logging port for gotd libraries.

A library writes structured records to a log.Logger; it never logs through a global and never imports a concrete logging framework. The consumer picks the backend by passing an adapter.

import (
    "github.com/gotd/log"
    "github.com/gotd/log/logslog" // stdlib log/slog backend, no extra deps
)

l := logslog.New(slog.Default())

if l.Enabled(ctx, log.LevelDebug) {
    l.Log(ctx, log.LevelDebug, "applying update",
        log.Int64("chat_id", chatID),
        log.Int("pts", pts),
    )
}

For ergonomic call sites, wrap a Logger in a Helper:

h := log.For(l) // log.For(nil) is a no-op Helper
h.Info(ctx, "connected", log.String("dc", dc))

Design

• Logger is two methods: Enabled(ctx, level) and Log(ctx, level, msg, ...Attr). The Enabled gate lets callers skip building attributes on hot paths.
• Attributes don't box scalars. log.Int64, log.Bool, log.Duration, … store into a compact Value; only Any, Error and Time carry an interface{}.
• Levels match log/slog (Debug=-4 … Error=8) so adapters convert by casting.
• No global state. Nothing here registers or reads a process-wide logger.

Modules

Module	Depends on
github.com/gotd/log	nothing (stdlib)
github.com/gotd/log/logslog	stdlib log/slog
github.com/gotd/log/logzap	go.uber.org/zap
github.com/gotd/log/logzerolog	github.com/rs/zerolog
github.com/gotd/log/loglogrus	github.com/sirupsen/logrus

Each backend adapter is a separate module so that its dependency never enters the core graph. Import only the one you use.

Implementing an adapter

An adapter implements log.Logger by switching on Attr.Value.Kind() and mapping each kind to the backend's typed field; fall back to Value.Any() for KindAny. See logslog, logzap, logzerolog and loglogrus for references.

Documentation

Overview

Package log defines a minimal, dependency-free logging port for gotd libraries.

A library writes structured records to a Logger and never logs through a global or imports a concrete logging framework. The consumer chooses the backend by passing an adapter: see the logslog and logzap subpackages for log/slog and go.uber.org/zap. When no logger is supplied, Nop discards every record.

The attribute model (Attr, Value) stores scalar values without boxing them into an interface, and the [Logger.Enabled] gate lets callers skip building attributes on hot paths when a level is disabled.

Index

• type Attr
  • func Any(key string, value any) Attr
  • func Bool(key string, value bool) Attr
  • func Duration(key string, value time.Duration) Attr
  • func Error(err error) Attr
  • func Float64(key string, value float64) Attr
  • func Group(key string, attrs ...Attr) Attr
  • func Int(key string, value int) Attr
  • func Int32(key string, value int32) Attr
  • func Int64(key string, value int64) Attr
  • func NamedError(key string, err error) Attr
  • func String(key, value string) Attr
  • func Stringer(key string, value fmt.Stringer) Attr
  • func Time(key string, value time.Time) Attr
  • func Uint64(key string, value uint64) Attr
• type CallerSkipper
• type Helper
  • func For(l Logger) Helper
  • func (h Helper) Debug(ctx context.Context, msg string, attrs ...Attr)
  • func (h Helper) Enabled(ctx context.Context, level Level) bool
  • func (h Helper) Error(ctx context.Context, msg string, attrs ...Attr)
  • func (h Helper) Info(ctx context.Context, msg string, attrs ...Attr)
  • func (h Helper) Logger() Logger
  • func (h Helper) Named(name string) Helper
  • func (h Helper) Warn(ctx context.Context, msg string, attrs ...Attr)
  • func (h Helper) With(attrs ...Attr) Helper
• type Kind
• type Level
  • func (l Level) String() string
• type Logger
  • func AddCallerSkip(l Logger, skip int) Logger
  • func Named(l Logger, name string) Logger
  • func OrNop(l Logger) Logger
  • func With(l Logger, attrs ...Attr) Logger
• type Namer
• type Value
  • func (v Value) Any() any
  • func (v Value) Bool() bool
  • func (v Value) Duration() time.Duration
  • func (v Value) Error() error
  • func (v Value) Float64() float64
  • func (v Value) Group() []Attr
  • func (v Value) Int64() int64
  • func (v Value) Kind() Kind
  • func (v Value) String() string
  • func (v Value) Time() time.Time
  • func (v Value) Uint64() uint64
• type Wither

Types

type Attr

type Attr struct {
	Key   string
	Value Value
}

Attr is a key-value pair attached to a log record.

func Any

func Any(key string, value any) Attr

Any returns an Attr holding an arbitrary value. Prefer the typed constructors for scalars: Any boxes the value into an interface.

func Bool

func Bool(key string, value bool) Attr

Bool returns a bool Attr.

func Duration

func Duration(key string, value time.Duration) Attr

Duration returns a time.Duration Attr.

func Error

func Error(err error) Attr

Error returns an Attr with the conventional key "error". A nil err is kept as a nil-valued error Attr.

func Float64

func Float64(key string, value float64) Attr

Float64 returns a float64 Attr.

func Group

func Group(key string, attrs ...Attr) Attr

Group returns an Attr whose value is the given child attributes. Adapters render it as a nested object. As a special case, an empty key inlines the children into the parent (like log/slog), matching zap's Inline.

func Int

func Int(key string, value int) Attr

Int returns an int Attr, stored as int64.

func Int32

func Int32(key string, value int32) Attr

Int32 returns an int32 Attr, stored as int64.

func Int64

func Int64(key string, value int64) Attr

Int64 returns an int64 Attr.

func NamedError

func NamedError(key string, err error) Attr

NamedError returns an error Attr under an explicit key. Unlike Error, which uses the conventional "error" key, this lets callers name the field.

func String

func String(key, value string) Attr

String returns a string Attr.

func Stringer

func Stringer(key string, value fmt.Stringer) Attr

Stringer returns an Attr holding value.String(). A nil Stringer yields the string "<nil>".

func Time

func Time(key string, value time.Time) Attr

Time returns a time.Time Attr.

func Uint64

func Uint64(key string, value uint64) Attr

Uint64 returns a uint64 Attr.

type CallerSkipper

type CallerSkipper interface {
	WithCallerSkip(skip int) Logger
}

CallerSkipper is an optional Logger capability: returning a child Logger that attributes records to a caller skip frames further up the stack. Wrappers that sit between the call site and the adapter (such as Helper) use it so the adapter still reports the real caller. Adapters that compute the caller implement it by mapping onto a native mechanism (e.g. zap.AddCallerSkip); loggers that do not are returned unchanged by AddCallerSkip.

type Helper

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

Helper wraps a Logger with leveled convenience methods for call sites. It is a thin value type; adapters implement Logger, not Helper.

Build one with For; the zero Helper logs to Nop.

func For

func For(l Logger) Helper

For returns a Helper writing to l, or to Nop if l is nil.

func (Helper) Debug

func (h Helper) Debug(ctx context.Context, msg string, attrs ...Attr)

Debug logs at LevelDebug.

func (Helper) Enabled

func (h Helper) Enabled(ctx context.Context, level Level) bool

Enabled reports whether a record at level would be recorded.

func (Helper) Error

func (h Helper) Error(ctx context.Context, msg string, attrs ...Attr)

Error logs at LevelError.

func (Helper) Info

func (h Helper) Info(ctx context.Context, msg string, attrs ...Attr)

Info logs at LevelInfo.

func (Helper) Logger

func (h Helper) Logger() Logger

Logger returns the underlying Logger, never nil.

func (Helper) Named

func (h Helper) Named(name string) Helper

Named returns a Helper whose logger is tagged with name. See Named.

func (Helper) Warn

func (h Helper) Warn(ctx context.Context, msg string, attrs ...Attr)

Warn logs at LevelWarn.

func (Helper) With

func (h Helper) With(attrs ...Attr) Helper

With returns a Helper whose logger attaches attrs to every record. See With.

type Kind

type Kind uint8

Kind enumerates the dynamic type stored in a Value.

const (
	KindAny Kind = iota
	KindString
	KindInt64
	KindUint64
	KindFloat64
	KindBool
	KindDuration
	KindTime
	KindError
	KindGroup
)

Value kinds.

type Level

type Level int

Level is the severity of a log record.

Values match log/slog (Debug=-4, Info=0, Warn=4, Error=8) so adapters convert by casting; this is an interop convenience, the values are defined here.

const (
	LevelDebug Level = -4
	LevelInfo  Level = 0
	LevelWarn  Level = 4
	LevelError Level = 8
)

Severity levels.

func (Level) String

func (l Level) String() string

String returns the canonical name of the level.

type Logger

type Logger interface {
	// Enabled reports whether a record at level would be recorded. Callers use
	// it to avoid building attributes on hot paths when logging is off.
	Enabled(ctx context.Context, level Level) bool
	// Log records one structured message. The attrs slice and its contents must
	// not be retained after Log returns.
	Log(ctx context.Context, level Level, msg string, attrs ...Attr)
}

Logger is the logging port a library writes structured records to.

Implementations must be safe for concurrent use by multiple goroutines.

var Nop Logger = nop{}

Nop is a Logger that discards every record. Its Enabled always returns false.

func AddCallerSkip

func AddCallerSkip(l Logger, skip int) Logger

AddCallerSkip returns a Logger that attributes records skip frames further up the stack, using the logger's native mechanism when it implements CallerSkipper. It returns l unchanged when skip is 0 or l does not track caller depth.

func Named

func Named(l Logger, name string) Logger

Named returns a child Logger tagged with name. It uses the logger's native Named when it implements Namer, otherwise it returns l unchanged (the name is advisory for backends without a naming concept). With an empty name it returns l unchanged.

func OrNop

func OrNop(l Logger) Logger

OrNop returns l, or Nop if l is nil. Callers store the result so no log site needs a nil check.

func With

func With(l Logger, attrs ...Attr) Logger

With returns a child Logger that attaches attrs to every record. It uses the logger's native With when it implements Wither, otherwise it wraps l. With no attrs it returns l unchanged.

type Namer

type Namer interface {
	Named(name string) Logger
}

Namer is an optional Logger capability: returning a child Logger tagged with a name. Adapters implement it to map onto a native mechanism (e.g. zap.Logger.Named); Named is a no-op for loggers that do not, since the name is advisory.

type Value

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

Value holds an attribute value without boxing scalar kinds into an interface.

num carries int64/uint64/float64/bool/duration bits; s carries strings; a carries the boxed value for KindAny, KindTime and KindError. It is modeled on slog.Value but kept deliberately small and explicit.

func (Value) Any

func (v Value) Any() any

Any returns the value boxed into an interface, regardless of kind.

func (Value) Bool

func (v Value) Bool() bool

Bool returns the value as bool. Valid for KindBool.

func (Value) Duration

func (v Value) Duration() time.Duration

Duration returns the value as time.Duration. Valid for KindDuration.

func (Value) Error

func (v Value) Error() error

Error returns the value as error, or nil. Valid for KindError.

func (Value) Float64

func (v Value) Float64() float64

Float64 returns the value as float64. Valid for KindFloat64.

func (Value) Group

func (v Value) Group() []Attr

Group returns the value's child attributes, or nil. Valid for KindGroup.

func (Value) Int64

func (v Value) Int64() int64

Int64 returns the value as int64. Valid for KindInt64 and KindDuration.

func (Value) Kind

func (v Value) Kind() Kind

Kind returns the value's kind.

func (Value) String

func (v Value) String() string

String renders the value to a string. For KindString it returns the string unchanged, so Value also satisfies fmt.Stringer.

func (Value) Time

func (v Value) Time() time.Time

Time returns the value as time.Time, or the zero time. Valid for KindTime.

func (Value) Uint64

func (v Value) Uint64() uint64

Uint64 returns the value as uint64. Valid for KindUint64.

type Wither

type Wither interface {
	With(attrs ...Attr) Logger
}

Wither is an optional Logger capability: returning a child Logger with attrs permanently attached to every record. Adapters implement it to map onto a native mechanism (e.g. zap.Logger.With); With falls back to a wrapper for loggers that do not.