gmetric

package
v2.8.6 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2024 License: MIT Imports: 11 Imported by: 6

Documentation

Overview

Package gmetric provides interface definitions and simple api for metric feature.

Index

Constants

View Source 
const (
	// MetricNamePattern is the regular expression pattern for validating metric name.
	MetricNamePattern = `[\w\.\-\/]`
)

Variables

This section is empty.

Functions

func IsEnabled 

func IsEnabled() bool

IsEnabled returns whether the metrics feature is enabled.

func SetGlobalAttributes 

func SetGlobalAttributes(attrs Attributes, option SetGlobalAttributesOption)

SetGlobalAttributes appends global attributes according `SetGlobalAttributesOption`. It appends global attributes to all metrics if given `SetGlobalAttributesOption` is empty. It appends global attributes to certain instrument by given `SetGlobalAttributesOption`.

func SetGlobalProvider 

func SetGlobalProvider(provider Provider)

SetGlobalProvider registers `provider` as the global Provider, which means the following metrics creating will be base on the global provider.

Types

type Attribute 

type Attribute interface {
	Key() string // The key for this attribute.
	Value() any  // The value for this attribute.
}

Attribute is the key-value pair item for Metric.

func NewAttribute 

func NewAttribute(key string, value any) Attribute

NewAttribute creates and returns an Attribute by given `key` and `value`.

type AttributeKey 

type AttributeKey string

AttributeKey is the attribute key.

type AttributeMap 

type AttributeMap map[string]any

AttributeMap contains the attribute key and value as map for easy filtering.

func (AttributeMap) Pick 

func (m AttributeMap) Pick(keys ...string) Attributes

Pick picks and returns attributes by given attribute keys.

func (AttributeMap) PickEx 

func (m AttributeMap) PickEx(keys ...string) Attributes

PickEx picks and returns attributes of which the given attribute keys does not in given `keys`.

func (AttributeMap) Sets 

func (m AttributeMap) Sets(attrMap map[string]any)

Sets adds given attribute map to current map.

type Attributes 

type Attributes []Attribute

Attributes is a slice of Attribute.

func CommonAttributes 

func CommonAttributes() Attributes

CommonAttributes returns the common used attributes for an instrument.

func GetGlobalAttributes 

func GetGlobalAttributes(option GetGlobalAttributesOption) Attributes

GetGlobalAttributes retrieves and returns the global attributes by `GetGlobalAttributesOption`. It returns the global attributes if given `GetGlobalAttributesOption` is empty. It returns global attributes of certain instrument if `GetGlobalAttributesOption` is not empty.

func (Attributes) MarshalJSON 

func (attrs Attributes) MarshalJSON() ([]byte, error)

MarshalJSON implements the interface MarshalJSON for json.Marshal.

func (Attributes) String 

func (attrs Attributes) String() string

MarshalJSON implements the interface MarshalJSON for json.Marshal.

type Callback 

type Callback func(ctx context.Context, obs Observer) error

Callback is a function registered with a Meter that makes observations for the set of instruments it is registered with. The Observer parameter is used to record measurement observations for these instruments.

type CallbackItem 

type CallbackItem struct {
	Callback    Callback           // Global callback.
	Metrics     []ObservableMetric // Callback on certain metrics.
	MeterOption MeterOption        // MeterOption is the option that the meter holds.
	Provider    Provider           // Provider is the Provider that the callback item is bound to.
}

CallbackItem is the global callback item registered.

func GetRegisteredCallbacks 

func GetRegisteredCallbacks() []CallbackItem

GetRegisteredCallbacks retrieves and returns the registered global callbacks. It truncates the callback slice is the callbacks are returned.

type Counter 

type Counter interface {
	Metric
	CounterPerformer
}

Counter is a Metric that represents a single numerical value that can ever goes up.

type CounterPerformer 

type CounterPerformer interface {
	// Inc increments the counter by 1. Use Add to increment it by arbitrary
	// non-negative values.
	Inc(ctx context.Context, option ...Option)

	// Add adds the given value to the counter. It panics if the value is < 0.
	Add(ctx context.Context, increment float64, option ...Option)
}

CounterPerformer performs operations for Counter metric.

type GetGlobalAttributesOption 

type GetGlobalAttributesOption struct {
	Instrument        string // Instrument specifies the instrument name.
	InstrumentVersion string // Instrument specifies the instrument version.
}

GetGlobalAttributesOption binds the global attributes to certain instrument.

type GlobalProvider 

type GlobalProvider interface {
	// Meter creates and returns the Meter by given MeterOption.
	Meter(option MeterOption) Meter
}

GlobalProvider hold the entry for creating Meter and Metric. The GlobalProvider has only one function for Meter creating, which is designed for convenient usage.

func GetGlobalProvider 

func GetGlobalProvider() GlobalProvider

GetGlobalProvider retrieves the GetGlobalProvider instance.

type Histogram 

type Histogram interface {
	Metric
	HistogramPerformer

	// Buckets returns the bucket slice of the Histogram.
	Buckets() []float64
}

Histogram counts individual observations from an event or sample stream in configurable static buckets (or in dynamic sparse buckets as part of the experimental Native Histograms, see below for more details). Similar to a Summary, it also provides a sum of observations and an observation count.

type HistogramPerformer 

type HistogramPerformer interface {
	// Record adds a single value to the histogram.
	// The value is usually positive or zero.
	Record(increment float64, option ...Option)
}

HistogramPerformer performs operations for Histogram metric.

type InstrumentInfo 

type InstrumentInfo interface {
	Name() string    // Name returns the instrument name of the metric.
	Version() string // Version returns the instrument version of the metric.
}

InstrumentInfo exports the instrument information of a metric.

type Meter 

type Meter interface {
	// Counter creates and returns a new Counter.
	Counter(name string, option MetricOption) (Counter, error)

	// UpDownCounter creates and returns a new UpDownCounter.
	UpDownCounter(name string, option MetricOption) (UpDownCounter, error)

	// Histogram creates and returns a new Histogram.
	Histogram(name string, option MetricOption) (Histogram, error)

	// ObservableCounter creates and returns a new ObservableCounter.
	ObservableCounter(name string, option MetricOption) (ObservableCounter, error)

	// ObservableUpDownCounter creates and returns a new ObservableUpDownCounter.
	ObservableUpDownCounter(name string, option MetricOption) (ObservableUpDownCounter, error)

	// ObservableGauge creates and returns a new ObservableGauge.
	ObservableGauge(name string, option MetricOption) (ObservableGauge, error)

	// MustCounter creates and returns a new Counter.
	// It panics if any error occurs.
	MustCounter(name string, option MetricOption) Counter

	// MustUpDownCounter creates and returns a new UpDownCounter.
	// It panics if any error occurs.
	MustUpDownCounter(name string, option MetricOption) UpDownCounter

	// MustHistogram creates and returns a new Histogram.
	// It panics if any error occurs.
	MustHistogram(name string, option MetricOption) Histogram

	// MustObservableCounter creates and returns a new ObservableCounter.
	// It panics if any error occurs.
	MustObservableCounter(name string, option MetricOption) ObservableCounter

	// MustObservableUpDownCounter creates and returns a new ObservableUpDownCounter.
	// It panics if any error occurs.
	MustObservableUpDownCounter(name string, option MetricOption) ObservableUpDownCounter

	// MustObservableGauge creates and returns a new ObservableGauge.
	// It panics if any error occurs.
	MustObservableGauge(name string, option MetricOption) ObservableGauge

	// RegisterCallback registers callback on certain metrics.
	// A callback is bound to certain component and version, it is called when the associated metrics are read.
	// Multiple callbacks on the same component and version will be called by their registered sequence.
	RegisterCallback(callback Callback, canBeCallbackMetrics ...ObservableMetric) error

	// MustRegisterCallback performs as RegisterCallback, but it panics if any error occurs.
	MustRegisterCallback(callback Callback, canBeCallbackMetrics ...ObservableMetric)
}

Meter hold the functions for kinds of Metric creating.

type MeterOption 

type MeterOption struct {
	// Instrument is the instrumentation name to bind this Metric to a global MeterProvider.
	// This is an optional configuration for a metric.
	Instrument string

	// InstrumentVersion is the instrumentation version to bind this Metric to a global MeterProvider.
	// This is an optional configuration for a metric.
	InstrumentVersion string

	// Attributes holds the constant key-value pair description metadata for all metrics of Meter.
	// This is an optional configuration for a meter.
	Attributes Attributes
}

MeterOption holds the creation option for a Meter.

type MeterPerformer 

type MeterPerformer interface {
	// CounterPerformer creates and returns a CounterPerformer that performs
	// the operations for Counter metric.
	CounterPerformer(name string, option MetricOption) (CounterPerformer, error)

	// UpDownCounterPerformer creates and returns a UpDownCounterPerformer that performs
	// the operations for UpDownCounter metric.
	UpDownCounterPerformer(name string, option MetricOption) (UpDownCounterPerformer, error)

	// HistogramPerformer creates and returns a HistogramPerformer that performs
	// the operations for Histogram metric.
	HistogramPerformer(name string, option MetricOption) (HistogramPerformer, error)

	// ObservableCounterPerformer creates and returns an ObservableCounterPerformer that performs
	// the operations for ObservableCounter metric.
	ObservableCounterPerformer(name string, option MetricOption) (ObservableCounterPerformer, error)

	// ObservableUpDownCounterPerformer creates and returns an ObservableUpDownCounterPerformer that performs
	// the operations for ObservableUpDownCounter metric.
	ObservableUpDownCounterPerformer(name string, option MetricOption) (ObservableUpDownCounterPerformer, error)

	// ObservableGaugePerformer creates and returns an ObservableGaugePerformer that performs
	// the operations for ObservableGauge metric.
	ObservableGaugePerformer(name string, option MetricOption) (ObservableGaugePerformer, error)

	// RegisterCallback registers callback on certain metrics.
	// A callback is bound to certain component and version, it is called when the associated metrics are read.
	// Multiple callbacks on the same component and version will be called by their registered sequence.
	RegisterCallback(callback Callback, canBeCallbackMetrics ...ObservableMetric) error
}

MeterPerformer manages all Metric performers creating.

type Metric 

type Metric interface {
	// Info returns the basic information of a Metric.
	Info() MetricInfo
}

Metric models a single sample value with its metadata being exported.

func GetAllMetrics 

func GetAllMetrics() []Metric

GetAllMetrics returns all Metric that created by current package.

type MetricCallback 

type MetricCallback func(ctx context.Context, obs MetricObserver) error

MetricCallback is automatically called when metric reader starts reading the metric value.

type MetricInfo 

type MetricInfo interface {
	Key() string                // Key returns the unique string key of the metric.
	Name() string               // Name returns the name of the metric.
	Help() string               // Help returns the help description of the metric.
	Unit() string               // Unit returns the unit name of the metric.
	Type() MetricType           // Type returns the type of the metric.
	Attributes() Attributes     // Attributes returns the constant attribute slice of the metric.
	Instrument() InstrumentInfo // InstrumentInfo returns the instrument info of the metric.
}

MetricInfo exports information of the Metric.

type MetricInitializer 

type MetricInitializer interface {
	// Init initializes the Metric in Provider creation.
	// It sets the metric performer which really takes action.
	Init(provider Provider) error
}

MetricInitializer manages the initialization for Metric. It is called internally in metric interface implements.

type MetricObserver 

type MetricObserver interface {
	// Observe observes the value for certain initialized Metric.
	// It adds the value to total result if the observed Metrics is type of Counter.
	// It sets the value as the result if the observed Metrics is type of Gauge.
	Observe(value float64, option ...Option)
}

MetricObserver sets the value for bound Metric.

type MetricOption 

type MetricOption struct {
	// Help provides information about this Histogram.
	// This is an optional configuration for a metric.
	Help string

	// Unit is the unit for metric value.
	// This is an optional configuration for a metric.
	Unit string

	// Attributes holds the constant key-value pair description metadata for this metric.
	// This is an optional configuration for a metric.
	Attributes Attributes

	// Buckets defines the buckets into which observations are counted.
	// For Histogram metric only.
	// A histogram metric uses default buckets if no explicit buckets configured.
	Buckets []float64

	// Callback function for metric, which is called when metric value changes.
	// For observable metric only.
	// If an observable metric has either Callback attribute nor global callback configured, it does nothing.
	Callback MetricCallback
}

MetricOption holds the basic options for creating a metric.

type MetricType 

type MetricType string

MetricType is the type of metric. 

const (
	MetricTypeCounter                 MetricType = `Counter`                 // Counter.
	MetricTypeUpDownCounter           MetricType = `UpDownCounter`           // UpDownCounter.
	MetricTypeHistogram               MetricType = `Histogram`               // Histogram.
	MetricTypeObservableCounter       MetricType = `ObservableCounter`       // ObservableCounter.
	MetricTypeObservableUpDownCounter MetricType = `ObservableUpDownCounter` // ObservableUpDownCounter.
	MetricTypeObservableGauge         MetricType = `ObservableGauge`         // ObservableGauge.
)

type ObservableCounter 

type ObservableCounter interface {
	Metric
	ObservableCounterPerformer
}

ObservableCounter is an instrument used to asynchronously record float64 measurements once per collection cycle. Observations are only made within a callback for this instrument. The value observed is assumed the to be the cumulative sum of the count.

type ObservableCounterPerformer 

type ObservableCounterPerformer = ObservableMetric

ObservableCounterPerformer is performer for observable ObservableCounter.

type ObservableGauge 

type ObservableGauge interface {
	Metric
	ObservableGaugePerformer
}

ObservableGauge is an instrument used to asynchronously record instantaneous float64 measurements once per collection cycle. Observations are only made within a callback for this instrument.

type ObservableGaugePerformer 

type ObservableGaugePerformer = ObservableMetric

ObservableGaugePerformer is performer for observable ObservableGauge.

type ObservableMetric 

type ObservableMetric interface {
	// contains filtered or unexported methods
}

ObservableMetric is an instrument used to asynchronously record instantaneous float64 measurements once per collection cycle.

type ObservableUpDownCounter 

type ObservableUpDownCounter interface {
	Metric
	ObservableUpDownCounterPerformer
}

ObservableUpDownCounter is used to synchronously record float64 measurements during a computational operation.

type ObservableUpDownCounterPerformer 

type ObservableUpDownCounterPerformer = ObservableMetric

ObservableUpDownCounterPerformer is performer for observable ObservableUpDownCounter.

type Observer 

type Observer interface {
	// Observe observes the value for certain initialized Metric.
	// It adds the value to total result if the observed Metrics is type of Counter.
	// It sets the value as the result if the observed Metrics is type of Gauge.
	Observe(m ObservableMetric, value float64, option ...Option)
}

Observer sets the value for certain initialized Metric.

type Option 

type Option struct {
	// Attributes holds the dynamic key-value pair metadata.
	Attributes Attributes
}

Option holds the option for perform a metric operation.

type PerformerExporter 

type PerformerExporter interface {
	// Performer exports internal Performer of Metric.
	// This is usually used by metric implements.
	Performer() any
}

PerformerExporter exports internal Performer of Metric. It is called internally in metric interface implements.

type Provider 

type Provider interface {
	// SetAsGlobal sets current provider as global meter provider for current process,
	// which makes the following metrics creating on this Provider, especially the metrics created in runtime.
	SetAsGlobal()

	// MeterPerformer creates and returns the MeterPerformer that can produce kinds of metric Performer.
	MeterPerformer(config MeterOption) MeterPerformer

	// ForceFlush flushes all pending metrics.
	//
	// This method honors the deadline or cancellation of ctx. An appropriate
	// error will be returned in these situations. There is no guaranteed that all
	// metrics be flushed or all resources have been released in these situations.
	ForceFlush(ctx context.Context) error

	// Shutdown shuts down the Provider flushing all pending metrics and
	// releasing any held computational resources.
	Shutdown(ctx context.Context) error
}

Provider manages all Metric exporting. Be caution that the Histogram buckets could not be customized if the creation of the Histogram is before the creation of Provider.

type SetGlobalAttributesOption 

type SetGlobalAttributesOption struct {
	// Instrument specifies the instrument name.
	Instrument string

	// Instrument specifies the instrument version.
	InstrumentVersion string

	// InstrumentPattern specifies instrument by regular expression on Instrument name.
	// Example:
	// 1. given `.+` will match all instruments.
	// 2. given `github.com/gogf/gf.+` will match all goframe instruments.
	InstrumentPattern string
}

SetGlobalAttributesOption binds the global attributes to certain instrument.

type UpDownCounter 

type UpDownCounter interface {
	Metric
	UpDownCounterPerformer
}

UpDownCounter is a Metric that represents a single numerical value that can ever goes up or down.

type UpDownCounterPerformer 

type UpDownCounterPerformer interface {
	// Inc increments the counter by 1. Use Add to increment it by arbitrary
	// non-negative values.
	Inc(ctx context.Context, option ...Option)

	// Dec decrements the Gauge by 1. Use Sub to decrement it by arbitrary values.
	Dec(ctx context.Context, option ...Option)

	// Add adds the given value to the counter. It panics if the value is < 0.
	Add(ctx context.Context, increment float64, option ...Option)
}

UpDownCounterPerformer performs operations for UpDownCounter metric.

Source Files

View all Source files

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.