timings

Documentation

Index

• Variables
• func Run(meas Measurer, label, summary string, f func(nestedTiming Measurer))
• type GetSaver
• 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 (t *Timings) AddTag(tag, value string)
  • func (t *Timings) Save(s GetSaver)
  • func (t *Timings) StartSpan(label, summary string) *Span
• type TimingsInfo
  • func Get(s GetSaver, 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 GetSaver

type GetSaver interface {
	// GetMaybeTimings gets the saved timings.
	// It will not return an error if none were saved yet.
	GetMaybeTimings(timings interface{}) error
	// SaveTimings saves the given timings.
	SaveTimings(timings interface{})
}

A GetSaver helps storing Timings (ignoring their details).

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 := state.TimingsForTask(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 (*Timings) AddTag

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

AddTag sets a tag on the Timings object.

func (*Timings) Save

func (t *Timings) Save(s GetSaver)

Save appends Timings data to a timings list in the GetSaver (usually state.State) and purges old timings, ensuring that up to MaxTimings are kept. Timings are only stored if their duration is greater than or equal to DurationThreshold. If GetSaver is a state.State, 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
	Duration      time.Duration
}

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

func Get

func Get(s GetSaver, 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. If GetSaver is a state.State, it's responsibility of the caller to lock the state before calling this function.