stats

package
v1.83.2 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: Apache-2.0 Imports: 5 Imported by: 19

Documentation

Overview

Package stats contains experimental metrics/stats API's.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultMetrics = stats.NewMetricSet()

DefaultMetrics are the default metrics registered through global metrics registry. This is written to at initialization time only, and is read only after initialization.

Functions

func CustomLabelFromContext added in v1.81.0 

func CustomLabelFromContext(ctx context.Context) string

CustomLabelFromContext returns the custom label from the context if it exists. If the custom label is not present, it returns an empty string.

func NewContextWithCustomLabel added in v1.81.0 

func NewContextWithCustomLabel(ctx context.Context, label string) context.Context

NewContextWithCustomLabel returns a new context with the provided custom label attached. The label will be propagated to all metric instruments specified in gRFC A108.

Types

type AsyncMetric added in v1.78.0 

type AsyncMetric interface {
	Descriptor() *MetricDescriptor
	// contains filtered or unexported methods
}

AsyncMetric is a marker interface for asynchronous metric types.

type AsyncMetricReporter added in v1.79.0 

type AsyncMetricReporter interface {
	// Report records metric values using the provided recorder.
	Report(AsyncMetricsRecorder) error
}

AsyncMetricReporter is an interface for types that record metrics asynchronously for the set of descriptors they are registered with. The AsyncMetricsRecorder parameter is used to record values for these metrics.

Implementations must make unique recordings across all registered AsyncMetricReporters. Meaning, they should not report values for a metric with the same attributes as another AsyncMetricReporter will report.

Implementations must be concurrent-safe.

type AsyncMetricReporterFunc added in v1.79.0 

type AsyncMetricReporterFunc func(AsyncMetricsRecorder) error

AsyncMetricReporterFunc is an adapter to allow the use of ordinary functions as AsyncMetricReporters.

func (AsyncMetricReporterFunc) Report added in v1.79.0 

func (f AsyncMetricReporterFunc) Report(r AsyncMetricsRecorder) error

Report calls f(r).

type AsyncMetricsRecorder added in v1.78.0 

type AsyncMetricsRecorder interface {
	// RecordInt64AsyncGauge records the measurement alongside labels on the int
	// count associated with the provided handle asynchronously
	RecordInt64AsyncGauge(handle *Int64AsyncGaugeHandle, incr int64, labels ...string)
}

AsyncMetricsRecorder records on asynchronous metrics derived from metric registry.

type Float64CountHandle 

type Float64CountHandle MetricDescriptor

Float64CountHandle is a typed handle for a float count metric. This handle is passed at the recording point in order to know which metric to record on.

func RegisterFloat64Count 

func RegisterFloat64Count(descriptor MetricDescriptor) *Float64CountHandle

RegisterFloat64Count registers the metric description onto the global registry. It returns a typed handle to use to recording data.

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. If multiple metrics are registered with the same name, this function will panic.

func (*Float64CountHandle) Descriptor 

func (h *Float64CountHandle) Descriptor() *MetricDescriptor

Descriptor returns the float64 count handle typecast to a pointer to a MetricDescriptor.

func (*Float64CountHandle) Record 

func (h *Float64CountHandle) Record(recorder MetricsRecorder, incr float64, labels ...string)

Record records the float64 count value on the metrics recorder provided.

type Float64HistoHandle 

type Float64HistoHandle MetricDescriptor

Float64HistoHandle is a typed handle for a float histogram metric. This handle is passed at the recording point in order to know which metric to record on.

func RegisterFloat64Histo 

func RegisterFloat64Histo(descriptor MetricDescriptor) *Float64HistoHandle

RegisterFloat64Histo registers the metric description onto the global registry. It returns a typed handle to use to recording data.

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. If multiple metrics are registered with the same name, this function will panic.

func (*Float64HistoHandle) Descriptor 

func (h *Float64HistoHandle) Descriptor() *MetricDescriptor

Descriptor returns the float64 histo handle typecast to a pointer to a MetricDescriptor.

func (*Float64HistoHandle) Record 

func (h *Float64HistoHandle) Record(recorder MetricsRecorder, incr float64, labels ...string)

Record records the float64 histo value on the metrics recorder provided.

type Int64AsyncGaugeHandle added in v1.78.0 

type Int64AsyncGaugeHandle MetricDescriptor

Int64AsyncGaugeHandle is a typed handle for an int gauge metric. This handle is passed at the recording point in order to know which metric to record on.

func RegisterInt64AsyncGauge added in v1.78.0 

func RegisterInt64AsyncGauge(descriptor MetricDescriptor) *Int64AsyncGaugeHandle

RegisterInt64AsyncGauge registers the metric description onto the global registry. It returns a typed handle to use for recording data.

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. If multiple metrics are registered with the same name, this function will panic.

func (*Int64AsyncGaugeHandle) Descriptor added in v1.78.0 

func (h *Int64AsyncGaugeHandle) Descriptor() *MetricDescriptor

Descriptor returns the int64 gauge handle typecast to a pointer to a MetricDescriptor.

func (*Int64AsyncGaugeHandle) Record added in v1.78.0 

func (h *Int64AsyncGaugeHandle) Record(recorder AsyncMetricsRecorder, value int64, labels ...string)

Record records the int64 gauge value on the metrics recorder provided.

type Int64CountHandle 

type Int64CountHandle MetricDescriptor

Int64CountHandle is a typed handle for a int count metric. This handle is passed at the recording point in order to know which metric to record on.

func RegisterInt64Count 

func RegisterInt64Count(descriptor MetricDescriptor) *Int64CountHandle

RegisterInt64Count registers the metric description onto the global registry. It returns a typed handle to use to recording data.

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. If multiple metrics are registered with the same name, this function will panic.

func (*Int64CountHandle) Descriptor 

func (h *Int64CountHandle) Descriptor() *MetricDescriptor

Descriptor returns the int64 count handle typecast to a pointer to a MetricDescriptor.

func (*Int64CountHandle) Record 

func (h *Int64CountHandle) Record(recorder MetricsRecorder, incr int64, labels ...string)

Record records the int64 count value on the metrics recorder provided.

type Int64GaugeHandle 

type Int64GaugeHandle MetricDescriptor

Int64GaugeHandle is a typed handle for an int gauge metric. This handle is passed at the recording point in order to know which metric to record on.

func RegisterInt64Gauge 

func RegisterInt64Gauge(descriptor MetricDescriptor) *Int64GaugeHandle

RegisterInt64Gauge registers the metric description onto the global registry. It returns a typed handle to use to recording data.

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. If multiple metrics are registered with the same name, this function will panic.

func (*Int64GaugeHandle) Descriptor 

func (h *Int64GaugeHandle) Descriptor() *MetricDescriptor

Descriptor returns the int64 gauge handle typecast to a pointer to a MetricDescriptor.

func (*Int64GaugeHandle) Record 

func (h *Int64GaugeHandle) Record(recorder MetricsRecorder, incr int64, labels ...string)

Record records the int64 histo value on the metrics recorder provided.

type Int64HistoHandle 

type Int64HistoHandle MetricDescriptor

Int64HistoHandle is a typed handle for an int histogram metric. This handle is passed at the recording point in order to know which metric to record on.

func RegisterInt64Histo 

func RegisterInt64Histo(descriptor MetricDescriptor) *Int64HistoHandle

RegisterInt64Histo registers the metric description onto the global registry. It returns a typed handle to use to recording data.

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. If multiple metrics are registered with the same name, this function will panic.

func (*Int64HistoHandle) Descriptor 

func (h *Int64HistoHandle) Descriptor() *MetricDescriptor

Descriptor returns the int64 histo handle typecast to a pointer to a MetricDescriptor.

func (*Int64HistoHandle) Record 

func (h *Int64HistoHandle) Record(recorder MetricsRecorder, incr int64, labels ...string)

Record records the int64 histo value on the metrics recorder provided.

type Int64UpDownCountHandle added in v1.77.0 

type Int64UpDownCountHandle MetricDescriptor

Int64UpDownCountHandle is a typed handle for an int up-down counter metric. This handle is passed at the recording point in order to know which metric to record on.

func RegisterInt64UpDownCount added in v1.77.0 

func RegisterInt64UpDownCount(descriptor MetricDescriptor) *Int64UpDownCountHandle

RegisterInt64UpDownCount registers the metric description onto the global registry. It returns a typed handle to use for recording data.

NOTE: this function must only be called during initialization time (i.e. in an init() function), and is not thread-safe. If multiple metrics are registered with the same name, this function will panic.

func (*Int64UpDownCountHandle) Descriptor added in v1.77.0 

func (h *Int64UpDownCountHandle) Descriptor() *MetricDescriptor

Descriptor returns the int64 up-down counter handle typecast to a pointer to a MetricDescriptor.

func (*Int64UpDownCountHandle) Record added in v1.77.0 

func (h *Int64UpDownCountHandle) Record(recorder MetricsRecorder, v int64, labels ...string)

Record records the int64 up-down counter value on the metrics recorder provided. The value 'v' can be positive to increment or negative to decrement.

type Metric 

type Metric = string

Metric was replaced by direct usage of strings.

type MetricDescriptor 

type MetricDescriptor struct {
	// The name of this metric. This name must be unique across the whole binary
	// (including any per call metrics). See
	// https://github.com/grpc/proposal/blob/master/A79-non-per-call-metrics-architecture.md#metric-instrument-naming-conventions
	// for metric naming conventions.
	Name string
	// The description of this metric.
	Description string
	// The unit (e.g. entries, seconds) of this metric.
	Unit string
	// The required label keys for this metric. These are intended to
	// metrics emitted from a stats handler.
	Labels []string
	// The optional label keys for this metric. These are intended to attached
	// to metrics emitted from a stats handler if configured.
	OptionalLabels []string
	// Whether this metric is on by default.
	Default bool
	// The type of metric. This is set by the metric registry, and not intended
	// to be set by a component registering a metric.
	Type MetricType
	// Bounds are the bounds of this metric. This only applies to histogram
	// metrics. If unset or set with length 0, stats handlers will fall back to
	// default bounds.
	Bounds []float64
}

MetricDescriptor is the data for a registered metric.

func DescriptorForMetric 

func DescriptorForMetric(metricName string) *MetricDescriptor

DescriptorForMetric returns the MetricDescriptor from the global registry.

Returns nil if MetricDescriptor not present.

type MetricType 

type MetricType int

MetricType is the type of metric. 

const (
	MetricTypeIntCount MetricType = iota
	MetricTypeFloatCount
	MetricTypeIntHisto
	MetricTypeFloatHisto
	MetricTypeIntGauge
	MetricTypeIntUpDownCount
	MetricTypeIntAsyncGauge
)

Type of metric supported by this instrument registry.

type Metrics 

type Metrics = stats.MetricSet

Metrics is an experimental legacy alias of the now-stable stats.MetricSet. Metrics will be deleted in a future release.

func NewMetrics 

func NewMetrics(metrics ...Metric) *Metrics

NewMetrics is an experimental legacy alias of the now-stable stats.NewMetricSet. NewMetrics will be deleted in a future release.

type MetricsRecorder 

type MetricsRecorder interface {
	// RecordInt64Count records the measurement alongside labels on the int
	// count associated with the provided handle.
	RecordInt64Count(handle *Int64CountHandle, incr int64, labels ...string)
	// RecordFloat64Count records the measurement alongside labels on the float
	// count associated with the provided handle.
	RecordFloat64Count(handle *Float64CountHandle, incr float64, labels ...string)
	// RecordInt64Histo records the measurement alongside labels on the int
	// histo associated with the provided handle.
	RecordInt64Histo(handle *Int64HistoHandle, incr int64, labels ...string)
	// RecordFloat64Histo records the measurement alongside labels on the float
	// histo associated with the provided handle.
	RecordFloat64Histo(handle *Float64HistoHandle, incr float64, labels ...string)
	// RecordInt64Gauge records the measurement alongside labels on the int
	// gauge associated with the provided handle.
	RecordInt64Gauge(handle *Int64GaugeHandle, incr int64, labels ...string)
	// RecordInt64UpDownCounter records the measurement alongside labels on the int
	// count associated with the provided handle.
	RecordInt64UpDownCount(handle *Int64UpDownCountHandle, incr int64, labels ...string)
	// RegisterAsyncReporter registers a reporter to produce metric values for
	// only the listed descriptors. The returned function must be called when
	// the metrics are no longer needed, which will remove the reporter. The
	// returned method needs to be idempotent and concurrent safe.
	RegisterAsyncReporter(reporter AsyncMetricReporter, descriptors ...AsyncMetric) func()

	// EnforceMetricsRecorderEmbedding is included to force implementers to embed
	// another implementation of this interface, allowing gRPC to add methods
	// without breaking users.
	internal.EnforceMetricsRecorderEmbedding
}

MetricsRecorder records on metrics derived from metric registry. Implementors must embed UnimplementedMetricsRecorder.

type UnimplementedMetricsRecorder added in v1.79.0 

type UnimplementedMetricsRecorder struct {
	internal.EnforceMetricsRecorderEmbedding
}

UnimplementedMetricsRecorder must be embedded to have forward compatible implementations.

func (UnimplementedMetricsRecorder) RecordFloat64Count added in v1.79.0 

func (UnimplementedMetricsRecorder) RecordFloat64Count(*Float64CountHandle, float64, ...string)

RecordFloat64Count provides a no-op implementation.

func (UnimplementedMetricsRecorder) RecordFloat64Histo added in v1.79.0 

func (UnimplementedMetricsRecorder) RecordFloat64Histo(*Float64HistoHandle, float64, ...string)

RecordFloat64Histo provides a no-op implementation.

func (UnimplementedMetricsRecorder) RecordInt64Count added in v1.79.0 

func (UnimplementedMetricsRecorder) RecordInt64Count(*Int64CountHandle, int64, ...string)

RecordInt64Count provides a no-op implementation.

func (UnimplementedMetricsRecorder) RecordInt64Gauge added in v1.79.0 

func (UnimplementedMetricsRecorder) RecordInt64Gauge(*Int64GaugeHandle, int64, ...string)

RecordInt64Gauge provides a no-op implementation.

func (UnimplementedMetricsRecorder) RecordInt64Histo added in v1.79.0 

func (UnimplementedMetricsRecorder) RecordInt64Histo(*Int64HistoHandle, int64, ...string)

RecordInt64Histo provides a no-op implementation.

func (UnimplementedMetricsRecorder) RecordInt64UpDownCount added in v1.79.0 

func (UnimplementedMetricsRecorder) RecordInt64UpDownCount(*Int64UpDownCountHandle, int64, ...string)

RecordInt64UpDownCount provides a no-op implementation.

func (UnimplementedMetricsRecorder) RegisterAsyncReporter added in v1.79.0 

func (UnimplementedMetricsRecorder) RegisterAsyncReporter(AsyncMetricReporter, ...AsyncMetric) func()

RegisterAsyncReporter provides a no-op implementation.

Source Files

View all Source files

Directories

Path Synopsis
Package telemetry defines stats APIs for interacting with telemetry labels.
 Package telemetry defines stats APIs for interacting with telemetry labels.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.