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 ¶
A Label provides a named dimension for a Metric.
func MustCreateLabel ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
WithLabels provides configuration options for a new Metric, providing the expected dimensions for data collection for that 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.
Source Files