timings

Documentation

Index

• Variables
• func Run(meas Measurer, label, summary string, f func(nestedTiming Measurer))
• type Measurer
• type Span
  • func (t *Span) StartSpan(label, summary string) *Span
  • func (t *Span) Stop()
• type TimingJSON
• type Timings
  • func New(tags map[string]string) *Timings
  • func NewForTask(task *state.Task) *Timings
  • func (t *Timings) AddTag(tag, value string)
  • func (t *Timings) LinkChange(change *state.Change)
  • func (t *Timings) Save(st *state.State)
  • func (t *Timings) StartSpan(label, summary string) *Span
• type TimingsInfo
  • func Get(st *state.State, maxLevel int, filter func(tags map[string]string) bool) ([]*TimingsInfo, error)

Variables

var DurationThreshold = 5 * time.Millisecond

Duration threshold - timings below the threshold will not be saved in the state. It can be changed only while holding state lock.

var MaxTimings = 100

Maximum number of timings to keep in state. It can be changed only while holding state lock.

Functions

func Run

func Run(meas Measurer, label, summary string, f func(nestedTiming Measurer))

Run creates, starts and then stops a nested Span under parent Measurer. The nested Span is passed to the measured function and can used to create further spans.

Types

type Measurer

type Measurer interface {
	StartSpan(label, summary string) *Span
}

type Span

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

Span represents a single performance measurement with optional nested measurements.

func (*Span) StartSpan

func (t *Span) StartSpan(label, summary string) *Span

StartSpan creates a new nested Span and initiates performance measurement. Nested measurements need to be stopped by calling Stop on it.

func (*Span) Stop

func (t *Span) Stop()

Stop stops the measurement.

type TimingJSON

type TimingJSON struct {
	Level    int           `json:"level,omitempty"`
	Label    string        `json:"label,omitempty"`
	Summary  string        `json:"summary,omitempty"`
	Duration time.Duration `json:"duration"`
}

TimingJSON and rootTimingsJSON aid in marshalling of flattened timings into state.

type Timings

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

Timings represents a tree of Span time measurements for a single execution of measured activity. A Timings tree object should be created at the beginning of the activity, followed by starting at least one Span, and then saved at the end of the activity.

Calling StartSpan on the Timings objects creates a Span and starts new performance measurement. Measurement needs to be finished by calling Stop function on the Span object. Nested measurements may be collected by calling StartSpan on Span objects. Similar to the above, nested measurements need to be finished by calling Stop on them.

Typical usage:

troot := timings.New(map[string]string{"task-id": task.ID(), "change-id": task.Change().ID()})
t1 := troot.StartSpan("computation", "...")
....
nestedTiming := t1.StartSpan("sub-computation", "...")
....
nestedTiming.Stop()
t1.Stop()
troot.Save()

In addition, a few helpers exist to simplify typical use cases, for example the above example can be reduced to:

troot := timings.NewForTask(task) // tags set automatically from task
t1 := troot.StartSpan("computation", "...")
timings.Run(t1, "sub-computation", "...", func(nested *Span) {
       ... expensive computation
})
t1.Stop()
troot.Save(task.State())

func New

func New(tags map[string]string) *Timings

New creates a Timings object. Tags provide extra information (such as "task-id" and "change-id") that can be used by the client when retrieving timings.

func NewForTask

func NewForTask(task *state.Task) *Timings

NewForTask creates a new Timings tree for the given task. Returned Timings tree has "task-id", "change-id" and "task-kind" tags set automatically from the respective task.

func (*Timings) AddTag

func (t *Timings) AddTag(tag, value string)

AddTag sets a tag on the Timings object.

func (*Timings) LinkChange

func (t *Timings) LinkChange(change *state.Change)

LinkChange sets the "change-id" tag on the Timings object.

func (*Timings) Save

func (t *Timings) Save(st *state.State)

Save appends Timings data to the "timings" list in the state and purges old timings, ensuring that up to MaxTimings are kept. Timings are only stored in state if their duration is greater than or equal to DurationThreshold. It's responsibility of the caller to lock the state before calling this function.

func (*Timings) StartSpan

func (t *Timings) StartSpan(label, summary string) *Span

StartSpan creates a Span and initiates performance measurement. Measurement needs to be stopped by calling Stop on it.

type TimingsInfo

type TimingsInfo struct {
	Tags          map[string]string
	NestedTimings []*TimingJSON
}

TimingsInfo holds a set of related nested timings and the tags set when they were captured.

func Get

func Get(st *state.State, maxLevel int, filter func(tags map[string]string) bool) ([]*TimingsInfo, error)

Get returns timings for which filter predicate is true and filters out nested timings whose level is greater than maxLevel. Negative maxLevel value disables filtering by level. It's responsibility of the caller to lock the state before calling this function.