README
¶
Measurement and Instrumentation package for Go
gomeasure is designed to provide fine grained (μs) timings for arbitrary
actions which can be reported on during runtime. Actions are named, and metrics
for all actions of the same name can be queried at any time.
Installation
go get github.com/domdavis/gomeasure
Usage
Recording an action is simply a case of:
t := gomeasure.Action("my action")
// Do something
t.Stop()
A set of Stats can then be retrieved using the same name:
s := gomeasure.Report("my action")
The returned Stats provide timings as time.Duration, which provides ns
results, however, the overhead for starting and stopping a timer is ~750ns
making the results accurate to μs granularity.
A full report on all actions being measured is provided using:
r := gomeasure.Snapshot()
Actions
Segregated sets of actions can be created if required:
a := gomeasure.NewActions()
t := a.TimerFor("my action")
t.Stop()
fmt.Println(a.Snapshot())
Documentation
¶
Overview ¶
Package gomeasure allows for arbitrary actions in code to be timed. Actions are grouped into sets by name, and metrics are provided for each named set.
Timing actions is simply a case of starting and stopping a time:
t := gomeasure.Action("my action")
// do something
t.Stop()
Metrics for a set of actions are retrieved using the same name passed to the Time function:
m := gomeasure.Report("my action")
The gomeasure package is thread safe, and multiple actions of the same name can be timed concurrently. While the metrics report to nanosecond precision, this package isn't meant to replace tools such as pprof as the timers themselves introduce an overhead (~750ns) on each call. Instead it's meant for longer running actions, like servicing http requests to give an overview of how aspects of an application are performing.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Actions ¶
type Actions interface {
// TimerFor returns a running Timer to measure the named action. Multiple
// Timers can be can be created for any given action, representing multiple
// instances of that action. These timers can be concurrent. When the timer
// is stopped the metrics for that timer will be added to this set of
// actions.
TimerFor(action string) Timer
// Report the Stats for the named action. If the action has not been
// recorded in this set then a set of empty Stats will be returned.
Report(action string) Stats
// Snapshot records a snapshot of Stats for all actions in this set.
Snapshot() []Stats
}
Actions holds metrics on a set of actions.
type Stats ¶
type Stats struct {
// Action is the name of the action the stats relate to.
Action string `json:"action"`
// Created is the timestamp when this set of stats was taken.
Created time.Time `json:"created"`
// Min is the shortest duration taken to perform the action. If no
// samples have been recorded then the duration will be 0.
Min time.Duration `json:"min"`
// Max is the longest duration taken to perform the action. If no samples
// have been recorded then the duration will be 0.
Max time.Duration `json:"max"`
// Mean is the average duration taken to perform the action. If no samples
// have been recorded then the duration will be 0.
Mean time.Duration `json:"mean"`
// Sigma is the standard deviation of durations for this action. If no
// samples have been recorded the duration will be 0, however, it is also
// possible to have a variance of 0 if actions have be recorded, but with no
// variance.
Sigma time.Duration `json:"s"`
// Total is the cumulative duration spent performing this action. If
// no samples have been recorded then the duration will be 0.
Total time.Duration `json:"total"`
// Samples is the total number of timings that have been recorded against
// this action.
Samples int `json:"samples"`
}
Stats holds the cumulative statistics for an action. All recorded samples for that action contribute to the stats figures. Once captures a set of stats will not be updated by the action is represents.
func EmptyStats ¶
EmptyStats returns a new, empty set of stats for the given action with all values zeroed, and the current time as the created time.
Example ¶
package main
import (
"fmt"
"github.com/domdavis/gomeasure"
)
func main() {
s := gomeasure.EmptyStats("my action")
fmt.Println(s.Action, s.Min, s.Max, s.Total, s.Mean, s.Sigma, s.Samples)
}
Output: my action 0s 0s 0s 0s 0s 0
func Report ¶
Report the Stats for the named action. If the action has not been recorded then a set of empty Stats will be returned.
func Snapshot ¶
func Snapshot() []Stats
Snapshot records a snapshot of Stats for all recorded actions.
func (Stats) String ¶
String returns the stats as a human readable string.
Example ¶
package main
import (
"fmt"
"strings"
"github.com/domdavis/gomeasure"
)
func main() {
s := gomeasure.EmptyStats("example")
split := strings.SplitAfter(s.String(), "]")
fmt.Println(split[0])
}
Output: Action: example [Min: 0s, Max: 0s, Mean: 0s, Sigma: 0s, Total: 0s, Samples: 0]
type Timer ¶
type Timer interface {
// Stop this Timer, recording the duration the timer was active for. Only
// the first call to Stop will record the timers duration. Further calls to
// Stop quietly fail.
Stop()
// Action returns the action this timer is timing.
Action() string
// Duration returns the recorded time this timer was active for. If the
// timer is still running Duration will return the current duration the
// timer has been running for.
Duration() time.Duration
}
Timer is the interface implemented by types that can time the duration of an action. Timers are started on creation and stopped on a call to Stop.
func Action ¶
Action returns a running Timer to measure an action. Multiple Timers can be can be created for any given action, representing multiple instances of that action. These timers can be concurrent.
Example ¶
package main
import (
"fmt"
"github.com/domdavis/gomeasure"
)
func main() {
// Action timers are arbitrary and can be started anywhere. The resultant
// timer needs to be stopped once the action has completed.
l := gomeasure.Action("example")
defer l.Stop()
for i := 0; i < 100; i++ {
// Multiple timers of the same name are allowed, and their results are
// added to the metrics set to give an overview of how the action is
// performing over multiple runs.
s := gomeasure.Action("sprintf")
_ = fmt.Sprintf("String %d", i)
s.Stop()
}
// A report on a named action can be pulled, and the metrics collected
// analysed.
r := gomeasure.Report("sprintf")
fmt.Println(r.Samples)
// An action timer that is still running will not have its metrics added to
// the set.
r = gomeasure.Report("example")
fmt.Println(r.Total)
// A snapshot of the actions will only include those actions that have seen
// at least one timer complete.
fmt.Println(len(gomeasure.Snapshot()))
}
Output: 100 0s 1
Source Files