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 RegisterPrometheusExporter ¶
func RegisterPrometheusExporter(reg prometheus.Registerer, gatherer prometheus.Gatherer) (http.Handler, error)
RegisterPrometheusExporter sets the global metrics handler to the provided Prometheus registerer and gatherer. Returned is an HTTP handler that can be used to read metrics from.
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 ...LabelValue) DerivedMetric
}
DerivedMetric 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) DerivedMetric
NewDerivedGauge creates a new Gauge Metric. That means that data collected by the new Metric will export only the last recorded value. Unlike NewGauge, the DerivedGauge accepts functions which are called to get the current value.
type Label ¶
type Label struct {
// contains filtered or unexported fields
}
A Label provides a named dimension for a Metric.
func CreateLabel ¶
CreateLabel will attempt to create a new Label.
func (Label) Value ¶
func (l Label) Value(value string) LabelValue
Value creates a new LabelValue for the Label.
type LabelValue ¶
type LabelValue struct {
// contains filtered or unexported fields
}
A LabelValue represents a Label with a specific value. It is used to record values for a Metric.
func (LabelValue) Key ¶
func (l LabelValue) Key() Label
func (LabelValue) Value ¶
func (l LabelValue) Value() string
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/istio/pkg/monitoring"
var (
method = monitoring.CreateLabel("method")
receivedBytes = monitoring.NewDistribution(
"received_bytes_total",
"Distribution of received bytes by method",
[]float64{10, 100, 1000, 10000},
monitoring.WithUnit(monitoring.Bytes),
)
)
func main() {
receivedBytes.With(method.Value("/projects/1")).Record(458)
}
Output:
func NewGauge ¶
NewGauge creates a new Gauge Metric. That means that data collected by the new Metric will export only the last recorded value.
Example ¶
package main
import "istio.io/istio/pkg/monitoring"
var pushLatency = monitoring.NewGauge(
"push_latency_seconds",
"Duration, measured in seconds, of the last push",
monitoring.WithUnit(monitoring.Seconds),
)
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 Sum Metric (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/istio/pkg/monitoring"
var (
protocol = monitoring.CreateLabel("protocol")
requests = monitoring.NewSum(
"requests_total",
"Number of requests handled, by protocol",
)
)
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:
type MetricDefinition ¶
MetricDefinition records a metric's metadata. This is used to work around two limitations of OpenTelemetry:
- (https://github.com/open-telemetry/opentelemetry-go/issues/4003) Histogram buckets cannot be defined per instrument. instead, we record all metric definitions and add them as Views at registration time.
- Support pkg/collateral, which wants to query all metrics. This cannot use a simple Collect() call, as this ignores any unused metrics.
func ExportMetricDefinitions ¶
func ExportMetricDefinitions() []MetricDefinition
ExportMetricDefinitions reports all currently registered metric definitions.
type Options ¶
type Options func(*options)
Options encode changes to the options passed to a Metric at creation time.
func WithEnabled ¶
WithEnabled allows a metric to be condition enabled if the provided function returns true. If disabled, metric operations will do nothing.
type RecordHook ¶
type RecordHook interface {
OnRecord(name string, tags []LabelValue, value float64)
}
RecordHook has a callback function which a measure is recorded.
Source Files
Directories