monitoring

Documentation

Index

• func MustRegister(metrics ...Metric)
• func RegisterRecordHook(name string, h RecordHook)
• type DerivedMetric
  • func NewDerivedGauge(name, description string, valueFn func() float64) DerivedMetric
• type Label
  • func MustCreateLabel(key string) Label
  • func (l Label) Value(value string) LabelValue
• type LabelValue
• type Metric
  • func NewDistribution(name, description string, bounds []float64, opts ...Options) Metric
  • func NewGauge(name, description string, opts ...Options) Metric
  • func NewSum(name, description string, opts ...Options) Metric
• type Options
  • func WithInt64Values() Options
  • func WithLabels(labels ...Label) Options
  • func WithUnit(unit Unit) Options
• type RecordHook
• type Unit

Functions

func MustRegister

func MustRegister(metrics ...Metric)

MustRegister is a helper function that will ensure that the provided Metrics are registered. If a metric fails to register, this method will panic.

func RegisterRecordHook

func RegisterRecordHook(name string, h RecordHook)

RegisterRecordHook adds a RecordHook for a given measure.

Types

type DerivedMetric

type DerivedMetric interface {
	// Name returns the name value of a DerivedMetric.
	Name() string

	// Register handles any required setup to ensure metric export.
	Register() error
}

DerivedMetrics can be used to supply values that dynamically derive from internal state, but are not updated based on any specific event. Their value will be calculated based on a value func that executes when the metrics are exported.

At the moment, only a Gauge type is supported.

func NewDerivedGauge

func NewDerivedGauge(name, description string, valueFn func() float64) DerivedMetric

NewDerivedGauge creates a new Metric with an aggregation type of LastValue that generates the value dynamically according to the provided function. This can be used for values based on querying some state within a system (when event-driven recording is not appropriate). NOTE: Labels not currently supported.

type Label

type Label tag.Key

A Label provides a named dimension for a Metric.

func MustCreateLabel

func MustCreateLabel(key string) Label

MustCreateLabel will attempt to create a new Label. If creation fails, then this method will panic.

func (Label) Value

func (l Label) Value(value string) LabelValue

Value creates a new LabelValue for the Label.

type LabelValue

type LabelValue tag.Mutator

A LabelValue represents a Label with a specific value. It is used to record values for a Metric.

type Metric

type Metric interface {
	// Increment records a value of 1 for the current measure. For Sums,
	// this is equivalent to adding 1 to the current value. For Gauges,
	// this is equivalent to setting the value to 1. For Distributions,
	// this is equivalent to making an observation of value 1.
	Increment()

	// Decrement records a value of -1 for the current measure. For Sums,
	// this is equivalent to subtracting -1 to the current value. For Gauges,
	// this is equivalent to setting the value to -1. For Distributions,
	// this is equivalent to making an observation of value -1.
	Decrement()

	// Name returns the name value of a Metric.
	Name() string

	// Record makes an observation of the provided value for the given measure.
	Record(value float64)

	// RecordInt makes an observation of the provided value for the measure.
	RecordInt(value int64)
	// With creates a new Metric, with the LabelValues provided. This allows creating
	// a set of pre-dimensioned data for recording purposes. This is primarily used
	// for documentation and convenience. Metrics created with this method do not need
	// to be registered (they share the registration of their parent Metric).
	With(labelValues ...LabelValue) Metric

	// Register configures the Metric for export. It MUST be called before collection
	// of values for the Metric. An error will be returned if registration fails.
	Register() error
}

A Metric collects numerical observations.

func NewDistribution

func NewDistribution(name, description string, bounds []float64, opts ...Options) Metric

NewDistribution creates a new Metric with an aggregation type of Distribution. This means that the data collected by the Metric will be collected and exported as a histogram, with the specified bounds.

func NewGauge

func NewGauge(name, description string, opts ...Options) Metric

NewGauge creates a new Metric with an aggregation type of LastValue. That means that data collected by the new Metric will export only the last recorded value.

func NewSum

func NewSum(name, description string, opts ...Options) Metric

NewSum creates a new Metric with an aggregation type of Sum (the values will be cumulative). That means that data collected by the new Metric will be summed before export.

type Options

type Options func(*options)

Options encode changes to the options passed to a Metric at creation time.

func WithInt64Values

func WithInt64Values() Options

WithInt64Values provides configuration options for a new Metric, indicating that recorded values will be saved as int64 values. Any float64 values recorded will converted to int64s via math.Floor-based conversion.

func WithLabels

func WithLabels(labels ...Label) Options

WithLabels provides configuration options for a new Metric, providing the expected dimensions for data collection for that Metric.

func WithUnit

func WithUnit(unit Unit) Options

WithUnit provides configuration options for a new Metric, providing unit of measure information for a new Metric.

type RecordHook

type RecordHook interface {
	OnRecordFloat64Measure(f *stats.Float64Measure, tags []tag.Mutator, value float64)
	OnRecordInt64Measure(i *stats.Int64Measure, tags []tag.Mutator, value int64)
}

RecordHook has a callback function which a measure is recorded.

type Unit

type Unit string

Unit encodes the standard name for describing the quantity measured by a Metric (if applicable).

const (
	None         Unit = "1"
	Bytes        Unit = "By"
	Seconds      Unit = "s"
	Milliseconds Unit = "ms"
)

Predefined units for use with the monitoring package.