metrics

Documentation

Index

• Variables
• func AddTags(ctx context.Context, tags ...Tag) context.Context
• func CaptureRuntimeMemStats(registry RootRegistry, collectionFreq time.Duration)
• func CaptureRuntimeMemStatsWithContext(ctx context.Context, registry RootRegistry, collectionFreq time.Duration) bool
• func DefaultSample() metrics.Sample
• func RunEmittingRegistry(ctx context.Context, registry Registry, emitFrequency time.Duration, ...)
• func WithRegistry(ctx context.Context, registry Registry) context.Context
• type MetricVal
  • func ToMetricVal(in interface{}) MetricVal
• type MetricVisitor
• type NoopRegistry
  • func (r NoopRegistry) Counter(_ string, _ ...Tag) metrics.Counter
  • func (r NoopRegistry) Each(MetricVisitor)
  • func (r NoopRegistry) Gauge(_ string, _ ...Tag) metrics.Gauge
  • func (r NoopRegistry) GaugeFloat64(_ string, _ ...Tag) metrics.GaugeFloat64
  • func (r NoopRegistry) Histogram(_ string, _ ...Tag) metrics.Histogram
  • func (r NoopRegistry) HistogramWithSample(_ string, _ metrics.Sample, _ ...Tag) metrics.Histogram
  • func (r NoopRegistry) Meter(_ string, _ ...Tag) metrics.Meter
  • func (r NoopRegistry) Timer(_ string, _ ...Tag) metrics.Timer
  • func (r NoopRegistry) Unregister(name string, tags ...Tag)
• type Registry
  • func FromContext(ctx context.Context) Registry
• type RootRegistry
  • func NewRootMetricsRegistry() RootRegistry
• type Tag
  • func MustNewTag(k, v string) Tag
  • func NewTag(k, v string) (Tag, error)
  • func NewTagWithFallbackValue(k, v, fallback string) Tag
  • func (t Tag) Key() string
  • func (t Tag) String() string
  • func (t Tag) Value() string
• type Tags
  • func MustNewTags(t map[string]string) Tags
  • func NewTags(t map[string]string) (Tags, error)
  • func TagsFromContext(ctx context.Context) Tags
  • func (t Tags) Len() int
  • func (t Tags) Less(i, j int) bool
  • func (t Tags) Swap(i, j int)
  • func (t Tags) ToMap() map[string]string
  • func (t Tags) ToSet() map[Tag]struct{}

Variables

var DefaultMetricsRegistry = NewRootMetricsRegistry()

Functions

func AddTags

func AddTags(ctx context.Context, tags ...Tag) context.Context

AddTags adds the provided tags to the provided context. If no tags are provided, the context is returned unchanged. Otherwise, a new context is returned with the new tags appended to any tags stored on the parent context. This function does not perform any de-duplication (that is, if a tag in the provided tags has the same key as an existing one, it will still be appended).

func CaptureRuntimeMemStats

func CaptureRuntimeMemStats(registry RootRegistry, collectionFreq time.Duration)

CaptureRuntimeMemStats registers runtime memory metrics collectors and spawns a goroutine which collects them every collectionFreq. This function can only be called once per lifetime of the process and only records metrics if the provided RootRegistry is a *rootRegistry.

Deprecated: use CaptureRuntimeMemStatsWithCancel instead. CaptureRuntimeMemStatsWithCancel has the following advantages over this function:

• Does not make assumptions about the concrete struct implementing of RootRegistry
• Does not restrict the function to being called only once globally
• Supports cancellation using a provided context
• Can tell if provided RootRegistry does not support Go runtime metric collection based on return value

func CaptureRuntimeMemStatsWithContext

func CaptureRuntimeMemStatsWithContext(ctx context.Context, registry RootRegistry, collectionFreq time.Duration) bool

CaptureRuntimeMemStatsWithContext creates a child registry of the provided registry that tracks Go runtime memory metrics and starts a goroutine that captures them to that registry every collectionFreq. This function only supports RootRegistry implementations that implement the metricsRegistryProvider interface -- if the provided RootRegistry does not satisfy this interface, this function is a no-op. This function returns true if it starts the runtime metric collection goroutine, false otherwise. If this function starts a goroutine, the goroutine runs until the provided context is done.

The gauges/metrics etc. used to track runtime statistics are shared globally and the values are reset every time this function is called (if it is not a no-op). Note that this function should typically only be called once per Go runtime, but no enforcement of this is performed.

func DefaultSample

func DefaultSample() metrics.Sample

func RunEmittingRegistry

func RunEmittingRegistry(ctx context.Context, registry Registry, emitFrequency time.Duration, visitor MetricVisitor)

RunEmittingRegistry periodically calls registry.Each with a provided visit function. See the documentation for Registry for the arguments of the visit function. RunEmittingRegistry blocks forever (or until ctx is cancelled) and should be started in its own goroutine.

func WithRegistry

func WithRegistry(ctx context.Context, registry Registry) context.Context

Types

type MetricVal

type MetricVal interface {
	Type() string
	Values() map[string]interface{}
}

func ToMetricVal

func ToMetricVal(in interface{}) MetricVal

type MetricVisitor

type MetricVisitor func(name string, tags Tags, value MetricVal)

MetricVisitor is a callback function type that can be passed into Registry.Each to report metrics into systems which consume metrics. An example use case is a MetricVisitor which writes its argument into a log file.

type NoopRegistry

type NoopRegistry struct{}

NoopRegistry is a "lightweight, high-speed implementation of Registry for when simplicity and performance matter above all else".

Useful in testing infrastructure. Doesn't collect, store, or emit any metrics.

func (NoopRegistry) Counter

func (r NoopRegistry) Counter(_ string, _ ...Tag) metrics.Counter

func (NoopRegistry) Each

func (r NoopRegistry) Each(MetricVisitor)

func (NoopRegistry) Gauge

func (r NoopRegistry) Gauge(_ string, _ ...Tag) metrics.Gauge

func (NoopRegistry) GaugeFloat64

func (r NoopRegistry) GaugeFloat64(_ string, _ ...Tag) metrics.GaugeFloat64

func (NoopRegistry) Histogram

func (r NoopRegistry) Histogram(_ string, _ ...Tag) metrics.Histogram

func (NoopRegistry) HistogramWithSample

func (r NoopRegistry) HistogramWithSample(_ string, _ metrics.Sample, _ ...Tag) metrics.Histogram

func (NoopRegistry) Meter

func (r NoopRegistry) Meter(_ string, _ ...Tag) metrics.Meter

func (NoopRegistry) Timer

func (r NoopRegistry) Timer(_ string, _ ...Tag) metrics.Timer

func (NoopRegistry) Unregister

func (r NoopRegistry) Unregister(name string, tags ...Tag)

type Registry

type Registry interface {
	Counter(name string, tags ...Tag) metrics.Counter
	Gauge(name string, tags ...Tag) metrics.Gauge
	GaugeFloat64(name string, tags ...Tag) metrics.GaugeFloat64
	Meter(name string, tags ...Tag) metrics.Meter
	Timer(name string, tags ...Tag) metrics.Timer
	Histogram(name string, tags ...Tag) metrics.Histogram
	HistogramWithSample(name string, sample metrics.Sample, tags ...Tag) metrics.Histogram
	// Each invokes the provided callback function on every user-defined metric registered on the router (including
	// those registered by sub-registries). Each is invoked on each metric in sorted order of the key.
	Each(MetricVisitor)
	// Unregister the metric with the given name and tags.
	Unregister(name string, tags ...Tag)
}

func FromContext

func FromContext(ctx context.Context) Registry

type RootRegistry

type RootRegistry interface {
	Registry

	// Subregistry returns a new subregistry of the root registry on which metrics can be registered.
	//
	// Specified tags will be always included in metrics emitted by a subregistry.
	// Deprecated: Use metrics.FromContext(ctx) instead to get a child registry with tags. Using subregistries and metric names
	// to namespace metrics is discouraged; metric tags should handle this instead.
	Subregistry(prefix string, tags ...Tag) Registry
}

RootRegistry is the root metric registry for a product. A root registry has a prefix and a product name.

Built-in Go metrics will be outputted as "<root-prefix>.<key>: <value>". Metrics registered on the root registry will be outputted as "<root-prefix>.<NAME>:<key>00: <value>". Metrics registered on subregistries of the root will be outputted as "<root-prefix>.<NAME>:<prefix>.<key>: <value>".

func NewRootMetricsRegistry

func NewRootMetricsRegistry() RootRegistry

NewRootMetricsRegistry creates a new root registry for metrics.

type Tag

type Tag struct {
	// contains filtered or unexported fields
}

A Tag is metadata associated with a metric. This tags implementation is designed to be compatible with the best practices for DataDog tags (https://docs.datadoghq.com/guides/tagging/). The key and value for a tag must both be non-empty.

func MustNewTag

func MustNewTag(k, v string) Tag

MustNewTag returns the result of calling NewTag, but panics if NewTag returns an error. Should only be used in instances where the inputs are statically defined and known to be valid.

func NewTag

func NewTag(k, v string) (Tag, error)

NewTag returns a tag that uses the provided key and value. The returned tag is normalized to conform with the DataDog tag specification. The key and value must be non-empty and the key must begin with a letter. The string form of the returned tag is "normalized(k):normalized(v)".

func NewTagWithFallbackValue

func NewTagWithFallbackValue(k, v, fallback string) Tag

NewTagWithFallbackValue returns the result of calling NewTag, and if that fails, calls MustNewTag with a fallback value. This function is useful when the value is provided as a runtime input and the desired behavior is to fall back to using a known valid value (e.g., "unknown") when the value is invalid. Note: because MustNewTag will panic if it fails, both the key and fallback value must be known valid.

func (Tag) Key

func (t Tag) Key() string

func (Tag) String

func (t Tag) String() string

The full representation of the tag, which is "key:value".

func (Tag) Value

func (t Tag) Value() string

type Tags

type Tags []Tag

func MustNewTags

func MustNewTags(t map[string]string) Tags

MustNewTags returns the result of calling NewTags, but panics if NewTags returns an error. Should only be used in instances where the inputs are statically defined and known to be valid.

func NewTags

func NewTags(t map[string]string) (Tags, error)

NewTags returns a slice of tags that use the provided key:value mapping.

func TagsFromContext

func TagsFromContext(ctx context.Context) Tags

TagsFromContext returns the tags stored on the provided context. May be nil if no tags have been set on the context.

func (Tags) Len

func (t Tags) Len() int

func (Tags) Less

func (t Tags) Less(i, j int) bool

func (Tags) Swap

func (t Tags) Swap(i, j int)

func (Tags) ToMap

func (t Tags) ToMap() map[string]string

ToMap returns the map representation of the tags, where the map key is the tag key and the map value is the tag value. If Tags contains multiple tags with the same key but different values, the output map will only contain one entry for the key (and the value will be the last value for that key that appeared in the Tags slice).

func (Tags) ToSet

func (t Tags) ToSet() map[Tag]struct{}