Documentation ¶
Index ¶
- Variables
- func AddErrorNameHandler(f func(error) (string, bool))
- func Collect(mon StatSource) map[string]float64
- func Funcs(cb func(f *Func))
- func NewId() int64
- func ResetContextSpan(ctx context.Context) context.Context
- func RootSpans(cb func(s Span))
- func Scopes(cb func(s *Scope))
- func Stats(cb func(key SeriesKey, field string, val float64))
- type Annotation
- type BoolVal
- type CallbackTransformer
- type CallbackTransformerFunc
- type Counter
- func (c *Counter) Current() (cur int64)
- func (c *Counter) Dec(delta int64) (current int64)
- func (c *Counter) High() (h int64)
- func (c *Counter) Inc(delta int64) (current int64)
- func (c *Counter) Low() (l int64)
- func (c *Counter) Reset() (val, low, high int64)
- func (c *Counter) Set(val int64) (former int64)
- func (c *Counter) Stats(cb func(key SeriesKey, field string, val float64))
- type DeltaTransformer
- type DiffMeter
- type DurationDist
- func (d *DurationDist) Copy() *DurationDist
- func (d *DurationDist) FullAverage() time.Duration
- func (d *DurationDist) Insert(val time.Duration)
- func (d *DurationDist) Query(quantile float64) time.Duration
- func (d *DurationDist) ReservoirAverage() time.Duration
- func (d *DurationDist) Reset()
- func (d *DurationDist) Stats(cb func(key SeriesKey, field string, val float64))
- type DurationVal
- type FloatDist
- func (d *FloatDist) Copy() *FloatDist
- func (d *FloatDist) FullAverage() float64
- func (d *FloatDist) Insert(val float64)
- func (d *FloatDist) Query(quantile float64) float64
- func (d *FloatDist) ReservoirAverage() float64
- func (d *FloatDist) Reset()
- func (d *FloatDist) Stats(cb func(key SeriesKey, field string, val float64))
- type FloatVal
- type Func
- func (f *Func) FullName() string
- func (f *Func) Id() int64
- func (f *Func) Parents(cb func(f *Func))
- func (f *Func) RemoteTrace(ctx *context.Context, _ int64, _ *Trace, _ ...interface{}) func(*error)
- func (f *Func) ResetTrace(ctx *context.Context, args ...interface{}) func(*error)
- func (f *Func) Scope() *Scope
- func (f *Func) ShortName() string
- func (f *Func) Task(ctx *context.Context, args ...interface{}) func(*error)
- type IntVal
- type Meter
- type Registry
- func (r *Registry) AllSpans(cb func(s *Span))
- func (r *Registry) Funcs(cb func(f *Func))
- func (r *Registry) ObserveTraces(cb func(*Trace)) (cancel func())
- func (r *Registry) Package() *Scope
- func (r *Registry) RootSpans(cb func(s *Span))
- func (r *Registry) ScopeNamed(name string) *Scope
- func (r *Registry) Scopes(cb func(s *Scope))
- func (r *Registry) Stats(cb func(key SeriesKey, field string, val float64))
- func (r *Registry) WithTransformers(t ...CallbackTransformer) *Registry
- type RunningTimer
- type Scope
- func (s *Scope) BoolVal(name string, tags ...SeriesTag) *BoolVal
- func (s *Scope) BoolValf(template string, args ...interface{}) *BoolVal
- func (s *Scope) Chain(source StatSource)
- func (s *Scope) Counter(name string, tags ...SeriesTag) *Counter
- func (s *Scope) DiffMeter(name string, m1, m2 *Meter, tags ...SeriesTag)
- func (s *Scope) DurationVal(name string, tags ...SeriesTag) *DurationVal
- func (s *Scope) Event(name string, tags ...SeriesTag)
- func (s *Scope) FloatVal(name string, tags ...SeriesTag) *FloatVal
- func (s *Scope) FloatValf(template string, args ...interface{}) *FloatVal
- func (s *Scope) Func() *Func
- func (s *Scope) FuncNamed(name string, tags ...SeriesTag) *Func
- func (s *Scope) Funcs(cb func(f *Func))
- func (s *Scope) Gauge(name string, cb func() float64)
- func (s *Scope) IntVal(name string, tags ...SeriesTag) *IntVal
- func (s *Scope) IntValf(template string, args ...interface{}) *IntVal
- func (s *Scope) Meter(name string, tags ...SeriesTag) *Meter
- func (s *Scope) Name() string
- func (s *Scope) Stats(cb func(key SeriesKey, field string, val float64))
- func (s *Scope) StructVal(name string, tags ...SeriesTag) *StructVal
- func (s *Scope) Task(tags ...SeriesTag) Task
- func (s *Scope) TaskNamed(name string, tags ...SeriesTag) Task
- func (s *Scope) Timer(name string, tags ...SeriesTag) *Timer
- type SeriesKey
- type SeriesTag
- type Span
- func (s *Span) Annotate(name, val string)
- func (s *Span) Annotations() []Annotation
- func (s *Span) Args() (rv []string)
- func (s *Span) Children(cb func(s *Span))
- func (s *Span) Duration() time.Duration
- func (s *Span) Func() *Func
- func (s *Span) Id() int64
- func (s *Span) Orphaned() (rv bool)
- func (s *Span) ParentId() (int64, bool)
- func (s *Span) Start() time.Time
- func (s *Span) String() string
- func (s *Span) Trace() *Trace
- func (s *Span) Value(key interface{}) interface{}
- type SpanCtxObserver
- type SpanObserver
- type StatSource
- type StatSourceFunc
- type StructVal
- type TagSet
- type Task
- type Timer
- type Trace
- func (t *Trace) Get(key interface{}) (val interface{})
- func (t *Trace) GetAll() (val map[interface{}]interface{})
- func (t *Trace) Id() int64
- func (t *Trace) ObserveSpans(observer SpanObserver) (cancel func())
- func (t *Trace) ObserveSpansCtx(observer SpanCtxObserver) (cancel func())
- func (t *Trace) Set(key, val interface{})
- func (t *Trace) Spans() int64
Constants ¶
This section is empty.
Variables ¶
var Default = NewRegistry()
Default is the default Registry
Functions ¶
func AddErrorNameHandler ¶
AddErrorNameHandler adds an error name handler function that will be consulted every time an error is captured for a task. The handlers will be called in the order they were registered with the most recently added handler first, until a handler returns true for the second return value. If no handler returns true, the error is checked to see if it implements an interface that allows it to name itself, and otherwise, monkit attempts to find a good name for most built in Go standard library errors.
func Collect ¶
func Collect(mon StatSource) map[string]float64
Collect takes something that implements the StatSource interface and returns a key/value map.
func NewId ¶
func NewId() int64
NewId returns a random integer intended for use when constructing new traces. See NewTrace.
func ResetContextSpan ¶
ResetContextSpan returns a new context with Span information removed.
Types ¶
type Annotation ¶
Annotation represents an arbitrary name and value string pair
type BoolVal ¶
type BoolVal struct {
// contains filtered or unexported fields
}
BoolVal keeps statistics about boolean values. It keeps the number of trues, number of falses, and the disposition (number of trues minus number of falses). Constructed using NewBoolVal, though its expected usage is like:
var mon = monkit.Package() func MyFunc() { ... mon.BoolVal("flipped").Observe(bool) ... }
type CallbackTransformer ¶
type CallbackTransformer interface {
Transform(func(SeriesKey, string, float64)) func(SeriesKey, string, float64)
}
CallbackTransformer will take a provided callback and return a transformed one.
type CallbackTransformerFunc ¶
type CallbackTransformerFunc func(func(SeriesKey, string, float64)) func(SeriesKey, string, float64)
CallbackTransformerFunc is a single function that implements CallbackTransformer's Transform.
type Counter ¶
type Counter struct {
// contains filtered or unexported fields
}
func (*Counter) Reset ¶
Reset resets all values including high/low counters and returns what they were.
type DeltaTransformer ¶
type DeltaTransformer struct {
// contains filtered or unexported fields
}
DeltaTransformer calculates deltas from any total fields. It keeps internal state to keep track of the previous totals, so care should be taken to use a different DeltaTransformer per output.
func NewDeltaTransformer ¶
func NewDeltaTransformer() *DeltaTransformer
NewDeltaTransformer creates a new DeltaTransformer with its own idea of the last totals seen.
type DiffMeter ¶
type DiffMeter struct {
// contains filtered or unexported fields
}
DiffMeter is a StatSource that shows the difference between the rates of two meters. Expected usage like:
var ( mon = monkit.Package() herps = mon.Meter("herps") derps = mon.Meter("derps") herpToDerp = mon.DiffMeter("herp_to_derp", herps, derps) )
func NewDiffMeter ¶
Constructs a DiffMeter.
type DurationDist ¶
type DurationDist struct {
// Low and High are the lowest and highest values observed since
// construction or the last reset.
Low, High time.Duration
// Recent is the last observed value.
Recent time.Duration
// Count is the number of observed values since construction or the last
// reset.
Count int64
// Sum is the sum of all the observed values since construction or the last
// reset.
Sum time.Duration
// contains filtered or unexported fields
}
DurationDist keeps statistics about values such as low/high/recent/average/quantiles. Not threadsafe. Construct with NewDurationDist(). Fields are expected to be read from but not written to.
func NewDurationDist ¶
func NewDurationDist(key SeriesKey) (d *DurationDist)
NewDurationDist creates a distribution of time.Durations.
func (*DurationDist) Copy ¶
func (d *DurationDist) Copy() *DurationDist
Copy returns a full copy of the entire distribution.
func (*DurationDist) FullAverage ¶
func (d *DurationDist) FullAverage() time.Duration
FullAverage calculates and returns the average of all inserted values.
func (*DurationDist) Insert ¶
func (d *DurationDist) Insert(val time.Duration)
Insert adds a value to the distribution, updating appropriate values.
func (*DurationDist) Query ¶
func (d *DurationDist) Query(quantile float64) time.Duration
Query will return the approximate value at the given quantile from the reservoir, where 0 <= quantile <= 1.
func (*DurationDist) ReservoirAverage ¶
func (d *DurationDist) ReservoirAverage() time.Duration
ReservoirAverage calculates the average of the current reservoir.
func (*DurationDist) Reset ¶
func (d *DurationDist) Reset()
type DurationVal ¶
type DurationVal struct {
// contains filtered or unexported fields
}
DurationVal is a convenience wrapper around an DurationVal. Constructed using NewDurationVal, though its expected usage is like:
var mon = monkit.Package() func MyFunc() { ... mon.DurationVal("time").Observe(val) ... }
func NewDurationVal ¶
func NewDurationVal(key SeriesKey) (v *DurationVal)
NewDurationVal creates an DurationVal
func (*DurationVal) Observe ¶
func (v *DurationVal) Observe(val time.Duration)
Observe observes an integer value
type FloatDist ¶
type FloatDist struct {
// Low and High are the lowest and highest values observed since
// construction or the last reset.
Low, High float64
// Recent is the last observed value.
Recent float64
// Count is the number of observed values since construction or the last
// reset.
Count int64
// Sum is the sum of all the observed values since construction or the last
// reset.
Sum float64
// contains filtered or unexported fields
}
FloatDist keeps statistics about values such as low/high/recent/average/quantiles. Not threadsafe. Construct with NewFloatDist(). Fields are expected to be read from but not written to.
func NewFloatDist ¶
NewFloatDist creates a distribution of float64s.
func (*FloatDist) FullAverage ¶
FullAverage calculates and returns the average of all inserted values.
func (*FloatDist) Query ¶
Query will return the approximate value at the given quantile from the reservoir, where 0 <= quantile <= 1.
func (*FloatDist) ReservoirAverage ¶
ReservoirAverage calculates the average of the current reservoir.
type FloatVal ¶
type FloatVal struct {
// contains filtered or unexported fields
}
FloatVal is a convenience wrapper around an FloatDist. Constructed using NewFloatVal, though its expected usage is like:
var mon = monkit.Package() func MyFunc() { ... mon.FloatVal("size").Observe(val) ... }
type Func ¶
type Func struct {
// contains filtered or unexported fields
}
Func represents a FuncStats bound to a particular function id, scope, and name. You should create a Func using the Func creation methods (Func/FuncNamed) on a Scope. If you want to manage installation bookkeeping yourself, create a FuncStats directly. Expected Func creation like:
var mon = monkit.Package() func MyFunc() { f := mon.Func() ... }
func (*Func) Parents ¶
Parents will call the given cb with all of the unique Funcs that so far have called this Func.
func (*Func) RemoteTrace ¶
RemoteTrace is like Func.Task, except you can specify the trace and parent span id. Needed for things like the Zipkin plugin.
func (*Func) ResetTrace ¶
ResetTrace is like Func.Task, except it always creates a new Trace.
func (*Func) Task ¶
Task returns a new Task for use on this Func. It also adds a new Span to the given ctx during execution.
var mon = monkit.Package() func MyFunc(ctx context.Context, arg1, arg2 string) (err error) { f := mon.Func() defer f.Task(&ctx, arg1, arg2)(&err) ... }
It's more expected for you to use mon.Task directly. See RemoteTrace or ResetTrace if you want greater control over creating new traces.
type IntVal ¶
type IntVal struct {
// contains filtered or unexported fields
}
IntVal is a convenience wrapper around an IntDist. Constructed using NewIntVal, though its expected usage is like:
var mon = monkit.Package() func MyFunc() { ... mon.IntVal("size").Observe(val) ... }
type Meter ¶
type Meter struct {
// contains filtered or unexported fields
}
Meter keeps track of events and their rates over time. Implements the StatSource interface. You should construct using NewMeter, though expected usage is like:
var ( mon = monkit.Package() meter = mon.Meter("meter") ) func MyFunc() { ... meter.Mark(4) // 4 things happened ... }
func (*Meter) Mark64 ¶
Mark64 marks amount events occurring in the current time window (int64 version).
func (*Meter) Reset ¶
Reset resets all internal state.
Useful when monitoring a counter that has overflowed.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry encapsulates all of the top-level state for a monitoring system. In general, only the Default registry is ever used.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry creates a NewRegistry, though you almost certainly just want to use Default.
func (*Registry) ObserveTraces ¶
ObserveTraces lets you observe all traces flowing through the system. The passed in callback 'cb' will be called for every new trace as soon as it starts, until the returned cancel method is called. Note: this only applies to all new traces. If you want to find existing or running traces, please pull them off of live RootSpans.
func (*Registry) Package ¶
Package creates a new monitoring Scope, named after the top level package. It's expected that you'll have something like
var mon = monkit.Package()
at the top of each package.
func (*Registry) RootSpans ¶
RootSpans will call 'cb' on all currently executing Spans with no live or reachable parent. See also AllSpans.
func (*Registry) ScopeNamed ¶
ScopeNamed is like Package, but lets you choose the name.
func (*Registry) WithTransformers ¶
func (r *Registry) WithTransformers(t ...CallbackTransformer) *Registry
WithTransformers returns a copy of Registry but with the additional CallbackTransformers applied to the Stats method.
type RunningTimer ¶
type RunningTimer struct {
// contains filtered or unexported fields
}
RunningTimer should be constructed from a Timer.
func (*RunningTimer) Elapsed ¶
func (r *RunningTimer) Elapsed() time.Duration
Elapsed just returns the amount of time since the timer started
func (*RunningTimer) Stop ¶
func (r *RunningTimer) Stop() time.Duration
Stop stops the timer, adds the duration to the statistics information, and returns the elapsed time.
type Scope ¶
type Scope struct {
// contains filtered or unexported fields
}
Scope represents a named collection of StatSources. Scopes are constructed through Registries.
func ScopeNamed ¶
ScopeNamed is just a wrapper around Default.ScopeNamed
func (*Scope) BoolValf ¶
BoolValf retrieves or creates a BoolVal after the given printf-formatted name.
func (*Scope) Chain ¶
func (s *Scope) Chain(source StatSource)
Chain registers a full StatSource as the given name in the Scope's StatSource table.
func (*Scope) DiffMeter ¶
DiffMeter retrieves or creates a DiffMeter after the given name and two submeters.
func (*Scope) DurationVal ¶
func (s *Scope) DurationVal(name string, tags ...SeriesTag) *DurationVal
DurationVal retrieves or creates a DurationVal after the given name.
func (*Scope) Event ¶
Event retrieves or creates a Meter named after the given name and then calls Mark(1) on that meter.
func (*Scope) FloatValf ¶
FloatValf retrieves or creates a FloatVal after the given printf-formatted name.
func (*Scope) Func ¶
Func retrieves or creates a Func named after the currently executing function name (via runtime.Caller. See FuncNamed to choose your own name.
func (*Scope) FuncNamed ¶
FuncNamed retrieves or creates a Func named using the given name and SeriesTags. See Func() for automatic name determination.
Each unique combination of keys/values in each SeriesTag will result in a unique Func. SeriesTags are not sorted, so keep the order consistent to avoid unintentionally creating new unique Funcs.
func (*Scope) Gauge ¶
Gauge registers a callback that returns a float as the given name in the Scope's StatSource table.
func (*Scope) IntValf ¶
IntValf retrieves or creates an IntVal after the given printf-formatted name.
func (*Scope) Task ¶
Task returns a new Task for use, creating an associated Func if necessary. It also adds a new Span to the given ctx during execution. Expected usage like:
var mon = monkit.Package() func MyFunc(ctx context.Context, arg1, arg2 string) (err error) { defer mon.Task()(&ctx, arg1, arg2)(&err) ... }
or
var ( mon = monkit.Package() funcTask = mon.Task() ) func MyFunc(ctx context.Context, arg1, arg2 string) (err error) { defer funcTask(&ctx, arg1, arg2)(&err) ... }
Task allows you to include SeriesTags. WARNING: Each unique tag key/value combination creates a unique Func and a unique series. SeriesTags should only be used for low-cardinality values that you intentionally wish to result in a unique series. Example:
func MyFunc(ctx context.Context, arg1, arg2 string) (err error) { defer mon.Task(monkit.NewSeriesTag("key1", "val1"))(&ctx)(&err) ... }
Task uses runtime.Caller to determine the associated Func name. See TaskNamed if you want to supply your own name. See Func.Task if you already have a Func.
If you want to control Trace creation, see Func.ResetTrace and Func.RemoteTrace
type SeriesKey ¶
SeriesKey represents an individual time series for monkit to output.
func NewSeriesKey ¶
NewSeriesKey constructs a new series with the minimal fields.
func (SeriesKey) String ¶
String returns a string representation of the series. For example, it returns something like `measurement,tag0=val0,tag1=val1`.
type SeriesTag ¶
type SeriesTag struct {
Key, Val string
}
SeriesTag is a key/value pair. When used with a measurement name, each set of unique key/value pairs represents a new unique series.
type Span ¶
Span represents a 'span' of execution. A span is analogous to a stack frame. Spans are constructed as a side-effect of Tasks.
func SpanFromCtx ¶
SpanFromCtx loads the current Span from the given context. This assumes the context already had a Span created through a Task.
func (*Span) Annotations ¶
func (s *Span) Annotations() []Annotation
Annotations returns any added annotations created through the Span Annotate method
func (*Span) Args ¶
Args returns the list of strings associated with the args given to the Task that created this Span.
type SpanCtxObserver ¶
type SpanCtxObserver interface { // Start is called when a Span starts. Start should return the context // this span should use going forward. ctx is the context it is currently // using. Start(ctx context.Context, s *Span) context.Context // Finish is called when a Span finishes, along with an error if any, whether // or not it panicked, and what time it finished. Finish(ctx context.Context, s *Span, err error, panicked bool, finish time.Time) }
SpanCtxObserver is the interface plugins must implement if they want to observe all spans on a given trace as they happen, or add to contexts as they pass through mon.Task()(&ctx)(&err) calls.
type SpanObserver ¶
type SpanObserver interface { // Start is called when a Span starts Start(s *Span) // Finish is called when a Span finishes, along with an error if any, whether // or not it panicked, and what time it finished. Finish(s *Span, err error, panicked bool, finish time.Time) }
SpanObserver is the interface plugins must implement if they want to observe all spans on a given trace as they happen.
type StatSource ¶
StatSource represents anything that can return named floating point values.
func StatSourceFromStruct ¶
func StatSourceFromStruct(key SeriesKey, structData interface{}) StatSource
StatSourceFromStruct uses the reflect package to implement the Stats call across all float64-castable fields of the struct.
func TransformStatSource ¶
func TransformStatSource(s StatSource, transformers ...CallbackTransformer) StatSource
TransformStatSource will make sure that a StatSource has the provided CallbackTransformers applied to callbacks given to the StatSource.
type StatSourceFunc ¶
type StructVal ¶
type StructVal struct {
// contains filtered or unexported fields
}
StructVal keeps track of a structure of data. Constructed using NewStructVal, though its expected usage is like:
var mon = monkit.Package() func MyFunc() { ... mon.StructVal("stats").Observe(stats) ... }
type TagSet ¶
type TagSet struct {
// contains filtered or unexported fields
}
TagSet is an immutible collection of tag, value pairs.
func (*TagSet) All ¶
All returns a map of all the key/value pairs in the tag set. It should not be modified.
type Task ¶
Tasks are created (sometimes implicitly) from Funcs. A Task should be called at the start of a monitored task, and its return value should be called at the stop of said task.
type Timer ¶
type Timer struct {
// contains filtered or unexported fields
}
Timer is a threadsafe convenience wrapper around a DurationDist. You should construct with NewTimer(), though the expected usage is from a Scope like so:
var mon = monkit.Package() func MyFunc() { ... timer := mon.Timer("event") // perform event timer.Stop() ... }
Timers implement StatSource.
type Trace ¶
type Trace struct {
// contains filtered or unexported fields
}
Trace represents a 'trace' of execution. A 'trace' is the collection of all of the 'spans' kicked off from the same root execution context. A trace is a concurrency-supporting analog of a stack trace, where a span is somewhat like a stack frame.
func (*Trace) Get ¶
func (t *Trace) Get(key interface{}) (val interface{})
Get returns a value associated with a key on a trace. See Set.
func (*Trace) GetAll ¶
func (t *Trace) GetAll() (val map[interface{}]interface{})
GetAll returns values associated with a trace. See SetAll.
func (*Trace) ObserveSpans ¶
func (t *Trace) ObserveSpans(observer SpanObserver) (cancel func())
ObserveSpans lets you register a SpanObserver for all future Spans on the Trace. The returned cancel method will remove your observer from the trace.
func (*Trace) ObserveSpansCtx ¶
func (t *Trace) ObserveSpansCtx(observer SpanCtxObserver) (cancel func())
ObserveSpansCtx lets you register a SpanCtxObserver for all future Spans on the Trace. The returned cancel method will remove your observer from the trace.