Documentation ¶
Overview ¶
Package stats exposes tools for producing application performance metrics to various metric collection backends.
Index ¶
- Variables
- func Add(name string, value interface{}, tags ...Tag)
- func AddAt(time time.Time, name string, value interface{}, tags ...Tag)
- func ContextAddTags(ctx context.Context, tags ...Tag) bool
- func ContextWithTags(ctx context.Context, tags ...Tag) context.Context
- func Flush()
- func Incr(name string, tags ...Tag)
- func IncrAt(time time.Time, name string, tags ...Tag)
- func Observe(name string, value interface{}, tags ...Tag)
- func ObserveAt(time time.Time, name string, value interface{}, tags ...Tag)
- func Register(handler Handler)
- func Report(metrics interface{}, tags ...Tag)
- func ReportAt(time time.Time, metrics interface{}, tags ...Tag)
- func Set(name string, value interface{}, tags ...Tag)
- func SetAt(time time.Time, name string, value interface{}, tags ...Tag)
- func TagsAreSorted(tags []Tag) bool
- type Buffer
- type Clock
- type Engine
- func (eng *Engine) Add(name string, value interface{}, tags ...Tag)
- func (eng *Engine) AddAt(t time.Time, name string, value interface{}, tags ...Tag)
- func (eng *Engine) Clock(name string, tags ...Tag) *Clock
- func (eng *Engine) ClockAt(name string, start time.Time, tags ...Tag) *Clock
- func (eng *Engine) Flush()
- func (eng *Engine) Incr(name string, tags ...Tag)
- func (eng *Engine) IncrAt(time time.Time, name string, tags ...Tag)
- func (eng *Engine) Observe(name string, value interface{}, tags ...Tag)
- func (eng *Engine) ObserveAt(t time.Time, name string, value interface{}, tags ...Tag)
- func (eng *Engine) Register(handler Handler)
- func (eng *Engine) Report(metrics interface{}, tags ...Tag)
- func (eng *Engine) ReportAt(time time.Time, metrics interface{}, tags ...Tag)
- func (eng *Engine) Set(name string, value interface{}, tags ...Tag)
- func (eng *Engine) SetAt(t time.Time, name string, value interface{}, tags ...Tag)
- func (eng *Engine) WithPrefix(prefix string, tags ...Tag) *Engine
- func (eng *Engine) WithTags(tags ...Tag) *Engine
- type Field
- type FieldType
- type Flusher
- type Handler
- type HandlerFunc
- type HistogramBuckets
- type Key
- type Measure
- type Serializer
- type Tag
- type Type
- type Value
Constants ¶
This section is empty.
Variables ¶
var Buckets = HistogramBuckets{}
Buckets is a registry where histogram buckets are placed. Some metric collection backends need to have histogram buckets defined by the program (like Prometheus), a common pattern is to use the init function of a package to register buckets for the various histograms that it produces.
var DefaultEngine = NewEngine(progname(), Discard)
DefaultEngine is the engine used by global helper functions.
var Discard = &discard{}
Discard is a handler that doesn't do anything with the measures it receives.
Functions ¶
func ContextAddTags ¶
ContextAddTags adds the given tags to the given context, if the tags have been set on any of the ancestor contexts. ContextAddTags returns true if tags were successfully appended to the context, and false otherwise.
The proper way to set tags on a context if you don't know whether or not tags already exist on the context is to first call ContextAddTags, and if that returns false, then call ContextWithTags instead.
func ContextWithTags ¶
ContextWithTags returns a new child context with the given tags. If the parent context already has tags set on it, they are _not_ propegated into the context children.
func Report ¶
func Report(metrics interface{}, tags ...Tag)
Report is a helper function that delegates to DefaultEngine.
func TagsAreSorted ¶
TagsAreSorted returns true if the given list of tags is sorted by tag name, false otherwise.
Types ¶
type Buffer ¶
type Buffer struct { // Target size of the memory buffer where metrics are serialized. // // If left to zero, a size of 1024 bytes is used as default (this is low, // you should set this value). // // Note that if the buffer size is small, the program may generate metrics // that don't fit into the configured buffer size. In that case the buffer // will still pass the serialized byte slice to its Serializer to leave the // decision of accepting or rejecting the metrics. BufferSize int // Size of the internal buffer pool, this controls how well the buffer // performs in highly concurrent environments. If unset, 2 x GOMAXPROCS // is used as a default value. BufferPoolSize int // The Serializer used to write the measures. // // This field cannot be nil. Serializer Serializer // contains filtered or unexported fields }
Buffer is the implementation of a measure handler which uses a Serializer to serialize the metric into a memory buffer and write them once the buffer has reached a target size.
type Clock ¶
type Clock struct {
// contains filtered or unexported fields
}
The Clock type can be used to report statistics on durations.
Clocks are useful to measure the duration taken by sequential execution steps and therefore aren't safe to be used concurrently by multiple goroutines.
Note: Clock times are reported to datadog in seconds. See `stats/datadog/measure.go`.
func (*Clock) Stamp ¶
Stamp reports the time difference between now and the last time the method was called (or since the clock was created).
The metric produced by this method call will have a "stamp" tag set to name.
func (*Clock) StampAt ¶
StampAt reports the time difference between now and the last time the method was called (or since the clock was created).
The metric produced by this method call will have a "stamp" tag set to name.
type Engine ¶
type Engine struct { // The measure handler that the engine forwards measures to. Handler Handler // A prefix set on all metric names produced by the engine. Prefix string // A list of tags set on all metrics produced by the engine. // // The list of tags has to be sorted. This is automatically managed by the // helper methods WithPrefix, WithTags and the NewEngine function. A program // that manipulates this field directly has to respect this requirement. Tags []Tag // Indicates whether to allow duplicated tags from the tags list before sending. // This option is turned off by default, ensuring that duplicate tags are removed. // Turn it on if you need to send the same tag multiple times with different values, // which is a special use case. AllowDuplicateTags bool // contains filtered or unexported fields }
An Engine carries the context for producing metrics, it is configured by setting the exported fields or using the helper methods to create sub-engines that inherit the configuration of the base they were created from.
The program must not modify the engine's handler, prefix, or tags after it started using it. If changes need to be made new engines must be created by calls to WithPrefix or WithTags.
func NewEngine ¶
NewEngine creates and returns a new engine configured with prefix, handler, and tags.
func WithPrefix ¶
WithPrefix returns a copy of the engine with prefix appended to default engine's current prefix and tags set to the merge of eng's current tags and those passed as argument. Both the default engine and the returned engine share the same handler.
func WithTags ¶
WithTags returns a copy of the engine with tags set to the merge of the default engine's current tags and those passed as arguments. Both the default engine and the returned engine share the same handler.
func (*Engine) ClockAt ¶
ClockAt returns a new clock identified by name and tags with a specified start time.
func (*Engine) Flush ¶
func (eng *Engine) Flush()
Flush flushes eng's handler (if it implements the Flusher interface).
func (*Engine) ReportAt ¶
ReportAt reports a set of metrics for a given time. The metrics must be of type struct, pointer to struct, or a slice or array to one of those. See MakeMeasures for details about how to make struct types exposing metrics.
func (*Engine) WithPrefix ¶
WithPrefix returns a copy of the engine with prefix appended to eng's current prefix and tags set to the merge of eng's current tags and those passed as argument. Both eng and the returned engine share the same handler.
type Field ¶
A Field is a key/value type that represents a single metric in a Measure.
type FieldType ¶
type FieldType int32
FieldType is an enumeration of the different metric types that may be set on a Field value.
type Flusher ¶
type Flusher interface {
Flush()
}
Flusher is an interface implemented by measure handlers in order to flush any buffered data.
type Handler ¶
type Handler interface { // HandleMeasures is called by the Engine on which the handler was set // whenever new measures are produced by the program. The first argument // is the time at which the measures were taken. // // The method must treat the list of measures as read-only values, and // must not retain pointers to any of the measures or their sub-fields // after returning. HandleMeasures(time time.Time, measures ...Measure) }
The Handler interface is implemented by types that produce measures to various metric collection backends.
func FilteredHandler ¶
FilteredHandler constructs a Handler that processes Measures with `filter` before forwarding to `h`.
func MultiHandler ¶
MultiHandler constructs a handler which dispatches measures to all given handlers.
type HandlerFunc ¶
HandlerFunc is a type alias making it possible to use simple functions as measure handlers.
func (HandlerFunc) HandleMeasures ¶
func (f HandlerFunc) HandleMeasures(time time.Time, measures ...Measure)
HandleMeasures calls f, satisfies the Handler interface.
type HistogramBuckets ¶
HistogramBuckets is a map type storing histogram buckets.
func (HistogramBuckets) Set ¶
func (b HistogramBuckets) Set(key string, buckets ...interface{})
Set sets a set of buckets to the given list of sorted values.
type Measure ¶
Measure is a type that represents a single measure made by the application. Measures are identified by a name, a set of fields that define what has been instrumented, and a set of tags representing different dimensions of the measure.
Implementations of the Handler interface receive lists of measures produced by the application, and assume the tags will be sorted.
func MakeMeasures ¶
MakeMeasures takes a struct value or a pointer to a struct value as argument and extracts and returns the list of measures that it represented.
The rules for converting values to measure are:
All fields exposing a 'metric' tag are expected to be of type bool, int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, uintptr, float32, float64, or time.Duration, and represent fields of the measures. The struct fields may also define a 'type' tag with a value of "counter", "gauge" or "histogram" to tune the behavior of the measure handlers.
All fields exposing a 'tag' tag are expected to be of type string and represent tags of the measures.
All struct fields are searched recursively for fields matching rule (1) and (2). Tags found within a struct are inherited by measures generated from sub-fields, they may also be overwritten.
type Serializer ¶
type Serializer interface { io.Writer // Appends the serialized representation of the given measures into b. // // The method must not retain any of the arguments. AppendMeasures(b []byte, time time.Time, measures ...Measure) []byte }
The Serializer interface is used to abstract the logic of serializing measures.
type Tag ¶
A Tag is a pair of a string key and value set on measures to define the dimensions of the metrics.
func ContextTags ¶
ContextTags returns a copy of the tags on the context if they exist and nil if they don't exist.
func SortTags ¶
SortTags sorts and deduplicates tags in-place, favoring later elements whenever a tag name duplicate occurs. The returned slice may be shorter than the input due to the elimination of duplicates.
type Type ¶
type Type int32
Type is an int32 type alias used to denote a values underlying type.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value is a wrapper type which is used to encapsulate underlying types (nil, bool, int, uintptr, float) in a single pseudo-generic type.
func MustValueOf ¶
MustValueOf asserts that v's underlying Type is valid, otherwise it panics.
func ValueOf ¶
func ValueOf(v interface{}) Value
ValueOf inspects v's underlying type and returns a Value which encapsulates this type. If the underlying type of v is not supported by Value's encapsulation its Type() will return stats.Invalid.
func (Value) Interface ¶
func (v Value) Interface() interface{}
Interface returns an new interface{} representation of this value. However, if the underlying Type is unsupported it panics.