monitoring

package
v0.0.0-...-7635388 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 21, 2023 License: Apache-2.0 Imports: 11 Imported by: 5

Documentation

Overview

Package monitoring provides a common instrumentation library for Istio components. Use of this library enables collateral generation for collected metrics, as well as a consistent developer experience across Istio codebases.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

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

	// ValueFrom is used to update the derived value with the provided
	// function and the associated label values. If the metric is unlabeled,
	// ValueFrom may be called without any labelValues. Otherwise, the labelValues
	// supplied MUST match the label keys supplied at creation time both in number
	// and in order.
	ValueFrom(valueFn func() float64, labelValues ...string)
}

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, opts ...DerivedOptions) 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).

type DerivedOptions

type DerivedOptions func(*derivedOptions)

DerivedOptions encode changes to the options passed to a DerivedMetric at creation time.

func WithLabelKeys

func WithLabelKeys(keys ...string) DerivedOptions

WithLabelKeys is used to configure the label keys used by a DerivedMetric. This option is mutually exclusive with the derived option `WithValueFrom` and will be ignored if that option is provided.

func WithValueFrom

func WithValueFrom(valueFn func() float64) DerivedOptions

WithValueFrom is used to configure the derivation of a DerivedMetric. This option is mutually exclusive with the derived option `WithLabelKeys`. It acts as syntactic sugar that elides the need to create a DerivedMetric (with no labels) and then call `ValueFrom`.

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.

Example
package main

import "istio.io/pkg/monitoring"

var (
	method = monitoring.MustCreateLabel("method")

	receivedBytes = monitoring.NewDistribution(
		"received_bytes_total",
		"Distribution of received bytes by method",
		[]float64{10, 100, 1000, 10000},
		monitoring.WithLabels(method),
		monitoring.WithUnit(monitoring.Bytes),
	)
)

func init() {
	monitoring.MustRegister(receivedBytes)
}

func main() {
	receivedBytes.With(method.Value("/projects/1")).Record(458)
}
Output:

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.

Example
package main

import "istio.io/pkg/monitoring"

var pushLatency = monitoring.NewGauge(
	"push_latency_seconds",
	"Duration, measured in seconds, of the last push",
	monitoring.WithUnit(monitoring.Seconds),
)

func init() {
	monitoring.MustRegister(pushLatency)
}

func main() {
	// only the last recorded value (99.2) will be exported for this gauge
	pushLatency.Record(77.3)
	pushLatency.Record(22.8)
	pushLatency.Record(99.2)
}
Output:

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.

Example
package main

import "istio.io/pkg/monitoring"

var (
	protocol = monitoring.MustCreateLabel("protocol")

	requests = monitoring.NewSum(
		"requests_total",
		"Number of requests handled, by protocol",
		monitoring.WithLabels(protocol),
	)
)

func init() {
	monitoring.MustRegister(requests)
}

func main() {
	// increment on every http request
	requests.With(protocol.Value("http")).Increment()

	// count gRPC requests double
	requests.With(protocol.Value("grpc")).Record(2)
}
Output:

func RegisterIf

func RegisterIf(metric Metric, enabled func() bool) Metric

RegisterIf is a helper function that will ensure that the provided Metric is registered if enabled function returns true. If a metric fails to register, this method will panic. It returns the registered metric or no-op metric based on enabled function. NOTE: It is important to use the returned Metric if RegisterIf is used.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL