Documentation ¶
Overview ¶
Package statsd contains a singleton statsd client for use in all other packages. It can be configured once at application startup, and imported by any package that wishes to record metrics.
Index ¶
- Constants
- Variables
- func SetBackend(b Backend)
- func WatchingTaggable(ctx context.Context, t Taggable) context.Context
- func WithTag(ctx context.Context, k string, v interface{}) context.Context
- func WithTaggable(ctx context.Context, t Taggable) context.Context
- func WithTags(ctx context.Context, t Tags) context.Context
- type Backend
- func NewBackend(impl, addr, prefix string, tags ...string) (Backend, error)
- func NewDatadogBackend(endpoint, namespace string, tags []string) (Backend, error)
- func NewForwardingBackend(handler ForwardHandler) Backend
- func NewLogBackend(namespace string, tags []string) Backend
- func NewNullBackend() Backend
- type Counter
- type Distribution
- type Finisher
- type ForwardHandler
- type Gaugor
- type Histogram
- type SetCounter
- type Taggable
- type Tags
- type Timer
- type Timing
Examples ¶
Constants ¶
const ( StatsdDefaultTags = "STATSD_DEFAULT_TAGS" DefaultSep = "," )
Variables ¶
var ErrUnknownBackend = fmt.Errorf("unknown statsd backend type")
ErrUnknownBackend is returned when the statsd backend implementation is not known.
Functions ¶
func SetBackend ¶
func SetBackend(b Backend)
SetBackend replaces the current backend with the given Backend.
func WatchingTaggable ¶
WatchingTaggable attaches a Taggable to a Context. When a metric is recorded, StatsTags() will be called and the tags will be appended.
Example ¶
SetBackend(exampleBackend) session := &testTaggable{"user": "anonymous", "email": "unknown"} ctx := context.Background() ctx = WatchingTaggable(ctx, session) metric := &Counter{Name: "page.view"} metric.Count(ctx, 10)
Output: count: page.view: 10 [email:unknown user:anonymous]
func WithTag ¶
WithTag attaches a key-value pair to a Context. Upon recording a metric, the pair will be attached as a tag.
func WithTaggable ¶
WithTaggable attaches a Taggable's tags to a Context. When a metric is recorded, those tags will be appended.
func WithTags ¶
WithTags attaches fields to a Context. Upon recording a metric, those fields will be attached as tags.
Example ¶
SetBackend(exampleBackend) ctx := context.Background() ctx = WithTags(ctx, Tags{"user": "anonymous", "email": "unknown"}) metric := &Counter{Name: "page.view"} metric.Count(ctx, 10)
Output: count: page.view: 10 [email:unknown user:anonymous]
Types ¶
type Backend ¶
type Backend interface { // Gauge measures the value of a metric at a particular time. Gauge(ctx context.Context, name string, value float64, tags []string, rate float64) error // Count tracks how many times something happened per second. Count(ctx context.Context, name string, value int64, tags []string, rate float64) error // Histogram tracks the statistical distribution of a set of values on each host. Histogram(ctx context.Context, name string, value float64, tags []string, rate float64) error // Distribution tracks the statistical distribution of a set of values across your infrastructure. Distribution(ctx context.Context, name string, value float64, tags []string, rate float64) error // Set counts the number of unique elements in a group. Set(ctx context.Context, name string, value string, tags []string, rate float64) error // Timing sends timing information, it is an alias for TimeInMilliseconds Timing(ctx context.Context, name string, value time.Duration, tags []string, rate float64) error }
Backend is an interface to a Statsd instance, currently implemented by nullBackend and NewDatadogBackend (go-dogstatsd).
The statsd protocol supports more types than we do: we can add these as we need them.
func NewBackend ¶
NewBackend returns the appropriate Backend for the given implementation and host. STATSD_DEFAULT_TAGS env variable will be read automatically and added to default tags.
func NewDatadogBackend ¶
NewDatadogBackend instantiates a new datadog/statsd connection. When running in containers at shopify, the endpoint should generally be "localhost:8125".
`namespace` is an optional prefix to be prepended to every metric submitted. It should end with a period to separate it from the metric name.
`tags` is a set of tags that will be included with every metric submitted. STATSD_DEFAULT_TAGS env variable will be read automatically and added to default tags.
func NewForwardingBackend ¶
func NewForwardingBackend(handler ForwardHandler) Backend
NewForwardingBackend creates a new Backend that sends all metrics to a ForwardHandler
func NewLogBackend ¶
NewLogBackend creates a new Backend that emits statsd metrics to the logger.
namespace is a global namespace to apply to every metric emitted. tags is a global set of tags that will be added to every metric emitted.
func NewNullBackend ¶
func NewNullBackend() Backend
NewNullBackend returns a new backend that no-ops every metric.
type Counter ¶
type Counter collector
Counter represents a count-type metric, which takes increments. https://docs.datadoghq.com/developers/metrics/counts/
func (*Counter) Count ¶
Count takes an integer -- typically 1 -- and increments the counter by this value.
The last parameter is an arbitrary array of tags as maps.
type Distribution ¶
type Distribution collector
Distribution tracks the statistical distribution of a set of values across your infrastructure. https://docs.datadoghq.com/developers/metrics/types/?tab=distribution#metric-type-definition
func (*Distribution) Distribution ¶
func (d *Distribution) Distribution(ctx context.Context, n float64, ts ...Tags)
The last parameter is an arbitrary array of tags as maps.
type ForwardHandler ¶
type Gaugor ¶
type Gaugor collector
Gaugor represents a gauge-type metric, which takes absolute values. https://docs.datadoghq.com/developers/metrics/gauges/
type Histogram ¶
type Histogram collector
Histogram tracks the statistical distribution of a set of values on each host. https://docs.datadoghq.com/developers/metrics/types/?tab=histogram#metric-type-definition
type SetCounter ¶
type SetCounter collector
SetCounter represents a set-type metric, which counts unique strings. https://docs.datadoghq.com/developers/metrics/sets/
func (*SetCounter) CountUnique ¶
func (c *SetCounter) CountUnique(ctx context.Context, value string, ts ...Tags)
CountUnique will count the number of unique elements in a group.
The last parameter is an arbitrary array of tags as maps.
type Taggable ¶
type Taggable interface {
StatsTags() Tags
}
Taggable is meant to be attached to a Context, such that StatsTags() will be appended to recorded metrics.
type Tags ¶
type Tags map[string]interface{}
func SelectKeys ¶
SelectKeys returns a map containing only the specified fields This argument purposefully not typed as Tags, such that logrus.Fields and Tags can both be passed without additional casting. Useful when specifying a Loggable/Taggable
type Timer ¶
type Timer collector
Timer represents a timer-type metric, which takes durations. It uses histograms, which is a datadog-specific extension. https://docs.datadoghq.com/developers/metrics/histograms/
func (*Timer) Duration ¶
Duration takes a time.Duration -- the time to complete the indicated operation -- and submits it to statsd.
The last parameter is an arbitrary array of tags as maps.
func (*Timer) StartTimer ¶
StartTimer provides a way to collect a duration metric for a function call in one line.
Examples:
func foo() { defer t.StartTimer().Finish() // ... } func foo() (err error) { defer t.StartTimer().SuccessFinish(&err) // ... }
type Timing ¶
type Timing collector
Timing represents a timing-type metric, which takes durations and includes percentiles, means, and other information along with the event. https://github.com/statsd/statsd/blob/master/docs/metric_types.md#timing