trace

Documentation

Overview

Package trace tracks execution across function (and machine) bounds. Build a trace with New(), and add nodes via With() or WithCaller(). Easily serialize and deserialize a Trace with String() and parse.Trace.

Index

• func CheckLabel(label string) error
• type Node
  • func NewNode(label string) *Node
  • func (n *Node) MarshalLogObject(oe zapcore.ObjectEncoder) error
  • func (n *Node) MarshalZerologObject(e *zerolog.Event)
  • func (n *Node) String() string
  • func (n *Node) WriteTo(w io.Writer) (int64, error)
• type Trace
  • func New() Trace
  • func (t Trace) Extend(label string) Trace
  • func (t Trace) MarshalLogArray(ae zapcore.ArrayEncoder) error
  • func (t Trace) MarshalZerologArray(a *zerolog.Array)
  • func (t Trace) String() string
  • func (t Trace) With(label string) Trace
  • func (t Trace) WithCaller(skip int) Trace
  • func (t Trace) WriteTo(w io.Writer) (n int64, err error)

Functions

func CheckLabel

func CheckLabel(label string) error

CheckLabel validates a label. A valid label is:

• non-empty
• contains no spaces (as unicode.IsSpace)
• does not contain the rune '!'.

Types

type Node

type Node struct {
	// Label is a user-defined tag. A label can't contain whitespace (see unicode.IsSpace) or the character '!'.
	Label string
	// ID is randomly generated as a uuidv4 when NewNode() is called.
	ID uuid.UUID
	// Start is
	Start time.Time
}

Node is an individual point in a trace. Build with NewNode().

func NewNode

func NewNode(label string) *Node

NewNode makes a new node from the label. A label can't be empty, contain whitespace, or the character '!'. Such characters will be replaced with their escape: eg, ' ' => "\0x20" Such a label will panic. Use CheckLabel(label) first if you're not sure.

func (*Node) MarshalLogObject

func (n *Node) MarshalLogObject(oe zapcore.ObjectEncoder) error

func (*Node) MarshalZerologObject

func (n *Node) MarshalZerologObject(e *zerolog.Event)

func (*Node) String

func (n *Node) String() string

String formats a node as <label>!<id>!<start>

func (*Node) WriteTo

func (n *Node) WriteTo(w io.Writer) (int64, error)

type Trace

type Trace []*Node

Trace execution across function (and machine) bounds by building a trace with New() and adding nodes at points of interest via With() or WithCaller().

func New

func New() Trace

New returns a nil trace, ready for use.

func (Trace) Extend

func (t Trace) Extend(label string) Trace

Extend the trace with a new node, returning a copy.

func (Trace) MarshalLogArray

func (t Trace) MarshalLogArray(ae zapcore.ArrayEncoder) error

func (Trace) MarshalZerologArray

func (t Trace) MarshalZerologArray(a *zerolog.Array)

func (Trace) String

func (t Trace) String() string

func (Trace) With

func (t Trace) With(label string) Trace

func (Trace) WithCaller

func (t Trace) WithCaller(skip int) Trace

func (Trace) WriteTo

func (t Trace) WriteTo(w io.Writer) (n int64, err error)

WriteTo the provided writer as a pretty-printed trace.