perf

Documentation

Index

• func AddEntries(t Tracker, entries []TimingEntry)
• func AddEntry(t Tracker, name string, dur time.Duration)
• func AddEntryDetails(t Tracker, name string, dur time.Duration, metrics map[string]int64, ...)
• func RenderTree(w io.Writer, entries []TimingEntry, opts RenderOptions) error
• type RenderOptions
• type Span
  • func NewSpan(t Tracker, name string) Span
• type TimingEntry
  • func Summary(entries []TimingEntry, topN int) []TimingEntry
• type Tracker
  • func New(enabled bool) Tracker
  • func NewWithNow(nowFn func() time.Time) Tracker

Functions

func AddEntries

func AddEntries(t Tracker, entries []TimingEntry)

AddEntries appends pre-built timing entries to the tracker.

func AddEntry

func AddEntry(t Tracker, name string, dur time.Duration)

AddEntry adds a pre-computed timing entry to the tracker. This is useful for recording wall-clock time that spans multiple Track calls.

func AddEntryDetails

func AddEntryDetails(t Tracker, name string, dur time.Duration, metrics map[string]int64, attrs map[string]string)

AddEntryDetails adds a pre-computed timing entry with optional numeric metrics and string attributes.

func RenderTree

func RenderTree(w io.Writer, entries []TimingEntry, opts RenderOptions) error

RenderTree writes a human-readable tree of entries to w. Each line shows the phase name, its wall-clock duration, and (unless disabled) its share of the parent's duration. Metrics and attributes appear inline.

parse                234ms  45%
├─ collect            12ms   5%  {files=120}
└─ scan              220ms  94%
   ├─ kotlin         100ms  45%
   └─ java           120ms  55%

Types

type RenderOptions

type RenderOptions struct {
	// MinDuration omits entries whose duration is shorter than this. Zero
	// disables filtering.
	MinDuration time.Duration
	// SortByDuration prints children sorted by duration descending instead
	// of insertion order.
	SortByDuration bool
	// HidePercents disables the "(NN%)" suffix on each line.
	HidePercents bool
	// HideMetrics disables the inline " {key=val key=val}" suffix.
	HideMetrics bool
}

RenderOptions tunes RenderTree output.

type Span

type Span interface {
	// SetAttr attaches a string attribute to the span. Last write wins.
	SetAttr(key, value string)
	// AddMetric attaches a numeric metric. Last write wins.
	AddMetric(key string, value int64)
	// Stop records the elapsed duration on the underlying Tracker. Safe to
	// call multiple times; subsequent calls are no-ops.
	Stop()
}

Span is a single in-progress timing. End it with Stop — typically via defer:

defer perf.NewSpan(t, "request").Stop()

or, if you need to attach metrics/attributes:

s := perf.NewSpan(t, "download")
defer s.Stop()
s.SetAttr("url", u)
s.AddMetric("bytes", n)

Spans against a no-op Tracker are zero-allocation no-ops.

func NewSpan

func NewSpan(t Tracker, name string) Span

NewSpan starts a span on t under name. Always pair with Stop, ideally via defer. If t is disabled (a no-op Tracker), the returned span is also a no-op and allocates nothing.

type TimingEntry

type TimingEntry struct {
	Name       string            `json:"name"`
	DurationMs int64             `json:"durationMs"`
	Children   []TimingEntry     `json:"children,omitempty"`
	Metrics    map[string]int64  `json:"metrics,omitempty"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

TimingEntry records the duration of a named phase.

func Summary

func Summary(entries []TimingEntry, topN int) []TimingEntry

Summary returns a flat top-N breakdown sorted by duration descending. It flattens the tree (every entry plus its descendants), sums duplicate names, and is useful for "where did time go" CLI output without nested structure.

type Tracker

type Tracker interface {
	// Track runs fn and records its duration under name.
	Track(name string, fn func() error) error
	// TrackVoid runs fn and records its duration under name. Use when fn
	// cannot fail; reserve Track for sites that genuinely propagate err.
	TrackVoid(name string, fn func())
	// Serial returns a child tracker that appends entries under name.
	Serial(name string) Tracker
	// End finalizes this child tracker and returns the parent.
	End() Tracker
	// GetTimings returns all recorded timing entries.
	GetTimings() []TimingEntry
	// IsEnabled reports whether timing is active.
	IsEnabled() bool
}

Tracker records hierarchical performance timings.

func New

func New(enabled bool) Tracker

New returns a Tracker. When enabled is false, the tracker is a no-op with zero overhead.

func NewWithNow

func NewWithNow(nowFn func() time.Time) Tracker

NewWithNow returns an enabled Tracker that reads time from nowFn. Pass a deterministic function to drive timings in tests.