log

Documentation

Overview

Package log provides the two halves of loom's logging model (DESIGN.md §6): a lock-free, non-blocking hot-path event Ring drained off the data plane, and an async leveled Logger for control/diagnostic output. The data plane must never block on logging, so the hot path only ever touches the Ring.

Index

• Constants
• type Drainer
  • func NewDrainer(ring *Ring, h Handler, poll time.Duration) *Drainer
  • func (d *Drainer) Run(ctx context.Context)
• type Event
• type Handler
• type Level
  • func (l Level) String() string
• type Logger
  • func New(out io.Writer, level Level) *Logger
  • func (l *Logger) Close()
  • func (l *Logger) Debug(msg string)
  • func (l *Logger) Dropped() uint64
  • func (l *Logger) Error(msg string)
  • func (l *Logger) Info(msg string)
  • func (l *Logger) Warn(msg string)
• type Ring
  • func NewRing(size int) *Ring
  • func (r *Ring) Cap() int
  • func (r *Ring) Dropped() uint64
  • func (r *Ring) Pop() (e Event, ok bool)
  • func (r *Ring) Push(e Event) bool

Constants

const (
	// EventSent records that one packet was sent (Value = bytes).
	EventSent uint16 = iota + 1
)

Event codes.

Types

type Drainer

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

Drainer moves events from a Ring to a Handler off the data plane. It polls the ring, draining it fully each pass, and does a final drain on shutdown.

func NewDrainer

func NewDrainer(ring *Ring, h Handler, poll time.Duration) *Drainer

NewDrainer returns a Drainer for ring calling h per event. poll <= 0 uses 1ms.

func (*Drainer) Run

func (d *Drainer) Run(ctx context.Context)

Run drains until ctx is cancelled, then drains any remaining events and exits.

type Event

type Event struct {
	Code  uint16
	Seq   uint64
	Value uint64
	Nanos int64
}

Event is a fixed-size, pointer-free hot-path record so pushing it allocates nothing and copies cheaply.

type Handler

type Handler func(Event)

Handler consumes a drained event. It runs off the hot path, so it may do real work (format, ship, aggregate).

type Level

type Level int

Level is a log severity.

const (
	LevelDebug Level = iota
	LevelInfo
	LevelWarn
	LevelError
)

Severity levels, increasing.

func (Level) String

func (l Level) String() string

String renders the level.

type Logger

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

Logger is an async leveled logger for control/diagnostic output. Log calls format a line and hand it to a background writer via a buffered channel; if the channel is full the line is dropped and counted, so logging never blocks the caller. It is NOT for the data-plane hot path — that uses Ring.

func New

func New(out io.Writer, level Level) *Logger

New starts a Logger writing lines >= level to out.

func (*Logger) Close

func (l *Logger) Close()

Close flushes buffered lines and stops the writer. The Logger must not be used after Close.

func (*Logger) Debug

func (l *Logger) Debug(msg string)

Debug logs at debug level.

func (*Logger) Dropped

func (l *Logger) Dropped() uint64

Dropped returns the number of lines dropped because the buffer was full.

func (*Logger) Error

func (l *Logger) Error(msg string)

Error logs at error level.

func (*Logger) Info

func (l *Logger) Info(msg string)

Info logs at info level.

func (*Logger) Warn

func (l *Logger) Warn(msg string)

Warn logs at warn level.

type Ring

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

Ring is a single-producer/single-consumer lock-free ring buffer. The data plane (one worker) Pushes; a drainer Pops. Push never blocks: when the ring is full it drops the event and increments a counter. Capacity is rounded up to a power of two.

func NewRing

func NewRing(size int) *Ring

NewRing returns a Ring with capacity >= size (rounded up to a power of two, minimum 2).

func (*Ring) Cap

func (r *Ring) Cap() int

Cap returns the ring capacity.

func (*Ring) Dropped

func (r *Ring) Dropped() uint64

Dropped returns the number of events dropped because the ring was full.

func (*Ring) Pop

func (r *Ring) Pop() (e Event, ok bool)

Pop dequeues the next event (single consumer); ok is false if empty.

func (*Ring) Push

func (r *Ring) Push(e Event) bool

Push enqueues e (single producer). It returns false and counts a drop if the ring is full. Never blocks; never allocates.