metric

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Dec 3, 2019 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

metric package provides an API for reporting diagnostic measurements using three basic kinds of instruments (or four, if calling one special case a separate one).

The three basic kinds are:

- counters - gauges - measures

All instruments report either float64 or int64 values.

The primary object that handles metrics is Meter. The implementation of the Meter is provided by SDK. Normally, the Meter is used directly only for the LabelSet generation, batch recording and the handle destruction.

LabelSet is a set of keys and values that are in a suitable, optimized form to be used by Meter.

Counters are instruments that are reporting a quantity or a sum. An example could be bank account balance or bytes downloaded. Counters can be created with either NewFloat64Counter or NewInt64Counter. Counters expect non-negative values by default to be reported. This can be changed with the WithMonotonic option (passing false as a parameter) passed to the Meter.New*Counter function - this allows reporting negative values. To report the new value, use an Add function.

Gauges are instruments that are reporting a current state of a value. An example could be voltage or temperature. Gauges can be created with either NewFloat64Gauge or NewInt64Gauge. Gauges by default have no limitations about reported values - they can be less or greater than the last reported value. This can be changed with the WithMonotonic option passed to the New*Gauge function - this permits the reported values only to go up. To report a new value, use the Set function.

Measures are instruments that are reporting values that are recorded separately to figure out some statistical properties from those values (like average). An example could be temperature over time or lines of code in the project over time. Measures can be created with either NewFloat64Measure or NewInt64Measure. Measures by default take only non-negative values. This can be changed with the WithAbsolute option (passing false as a parameter) passed to the New*Measure function - this allows reporting negative values too. To report a new value, use the Record function.

All the basic kinds of instruments also support creating handles for a potentially more efficient reporting. The handles have the same function names as the instruments (so counter handle has Add, gauge handle has Set and measure handle has Record). Handles can be created with the AcquireHandle function of the respective instrument. When done with the handle, call Release on it.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyCounterOptions 

func ApplyCounterOptions(opts *Options, cos ...CounterOptionApplier)

ApplyCounterOptions is a helper that applies all the counter options to passed opts.

func ApplyGaugeOptions 

func ApplyGaugeOptions(opts *Options, gos ...GaugeOptionApplier)

ApplyGaugeOptions is a helper that applies all the gauge options to passed opts.

func ApplyMeasureOptions 

func ApplyMeasureOptions(opts *Options, mos ...MeasureOptionApplier)

ApplyMeasureOptions is a helper that applies all the measure options to passed opts.

Types

type CounterGaugeOptionApplier 

type CounterGaugeOptionApplier interface {
	CounterOptionApplier
	GaugeOptionApplier
}

CounterGaugeOptionApplier is an interface for applying metric options that are valid for counter or gauge metrics.

func WithMonotonic 

func WithMonotonic(monotonic bool) CounterGaugeOptionApplier

WithMonotonic sets whether a counter or a gauge is not permitted to go down.

type CounterOptionApplier 

type CounterOptionApplier interface {
	// ApplyCounterOption is used to make some general or
	// counter-specific changes in the Options.
	ApplyCounterOption(*Options)
}

CounterOptionApplier is an interface for applying metric options that are valid only for counter metrics.

type Float64Counter 

type Float64Counter struct {
	// contains filtered or unexported fields
}

Float64Counter is a metric that accumulates float64 values.

func WrapFloat64CounterInstrument 

func WrapFloat64CounterInstrument(instrument InstrumentImpl) Float64Counter

WrapFloat64CounterInstrument wraps the instrument in the type-safe wrapper as an floating point counter.

It is mostly intended for SDKs.

func (*Float64Counter) AcquireHandle 

func (c *Float64Counter) AcquireHandle(labels LabelSet) (h Float64CounterHandle)

AcquireHandle creates a handle for this counter. The labels should contain the keys and values for each key specified in the counter with the WithKeys option.

If the labels do not contain a value for the key specified in the counter with the WithKeys option, then the missing value will be treated as unspecified.

func (*Float64Counter) Add 

func (c *Float64Counter) Add(ctx context.Context, value float64, labels LabelSet)

Add adds the value to the counter's sum. The labels should contain the keys and values for each key specified in the counter with the WithKeys option.

If the labels do not contain a value for the key specified in the counter with the WithKeys option, then the missing value will be treated as unspecified.

func (Float64Counter) Impl 

func (m Float64Counter) Impl() InstrumentImpl

func (*Float64Counter) Measurement 

func (c *Float64Counter) Measurement(value float64) Measurement

Measurement creates a Measurement object to use with batch recording.

type Float64CounterHandle 

type Float64CounterHandle struct {
	// contains filtered or unexported fields
}

Float64CounterHandle is a handle for Float64Counter.

It inherits the Release function from commonHandle.

func (*Float64CounterHandle) Add 

func (h *Float64CounterHandle) Add(ctx context.Context, value float64)

Add adds the value to the counter's sum.

func (Float64CounterHandle) Release 

func (h Float64CounterHandle) Release()

type Float64Gauge 

type Float64Gauge struct {
	// contains filtered or unexported fields
}

Float64Gauge is a metric that stores the last float64 value.

func WrapFloat64GaugeInstrument 

func WrapFloat64GaugeInstrument(instrument InstrumentImpl) Float64Gauge

WrapFloat64GaugeInstrument wraps the instrument in the type-safe wrapper as an floating point gauge.

It is mostly intended for SDKs.

func (*Float64Gauge) AcquireHandle 

func (g *Float64Gauge) AcquireHandle(labels LabelSet) (h Float64GaugeHandle)

AcquireHandle creates a handle for this gauge. The labels should contain the keys and values for each key specified in the gauge with the WithKeys option.

If the labels do not contain a value for the key specified in the gauge with the WithKeys option, then the missing value will be treated as unspecified.

func (Float64Gauge) Impl 

func (m Float64Gauge) Impl() InstrumentImpl

func (*Float64Gauge) Measurement 

func (g *Float64Gauge) Measurement(value float64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (*Float64Gauge) Set 

func (g *Float64Gauge) Set(ctx context.Context, value float64, labels LabelSet)

Set assigns the passed value to the value of the gauge. The labels should contain the keys and values for each key specified in the gauge with the WithKeys option.

If the labels do not contain a value for the key specified in the gauge with the WithKeys option, then the missing value will be treated as unspecified.

type Float64GaugeHandle 

type Float64GaugeHandle struct {
	// contains filtered or unexported fields
}

Float64GaugeHandle is a handle for Float64Gauge.

It inherits the Release function from commonHandle.

func (Float64GaugeHandle) Release 

func (h Float64GaugeHandle) Release()

func (*Float64GaugeHandle) Set 

func (h *Float64GaugeHandle) Set(ctx context.Context, value float64)

Set assigns the passed value to the value of the gauge.

type Float64Measure 

type Float64Measure struct {
	// contains filtered or unexported fields
}

Float64Measure is a metric that records float64 values.

func WrapFloat64MeasureInstrument 

func WrapFloat64MeasureInstrument(instrument InstrumentImpl) Float64Measure

WrapFloat64MeasureInstrument wraps the instrument in the type-safe wrapper as an floating point measure.

It is mostly intended for SDKs.

func (*Float64Measure) AcquireHandle 

func (c *Float64Measure) AcquireHandle(labels LabelSet) (h Float64MeasureHandle)

AcquireHandle creates a handle for this measure. The labels should contain the keys and values for each key specified in the measure with the WithKeys option.

If the labels do not contain a value for the key specified in the measure with the WithKeys option, then the missing value will be treated as unspecified.

func (Float64Measure) Impl 

func (m Float64Measure) Impl() InstrumentImpl

func (*Float64Measure) Measurement 

func (c *Float64Measure) Measurement(value float64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (*Float64Measure) Record 

func (c *Float64Measure) Record(ctx context.Context, value float64, labels LabelSet)

Record adds a new value to the list of measure's records. The labels should contain the keys and values for each key specified in the measure with the WithKeys option.

If the labels do not contain a value for the key specified in the measure with the WithKeys option, then the missing value will be treated as unspecified.

type Float64MeasureHandle 

type Float64MeasureHandle struct {
	// contains filtered or unexported fields
}

Float64MeasureHandle is a handle for Float64Measure.

It inherits the Release function from commonHandle.

func (*Float64MeasureHandle) Record 

func (h *Float64MeasureHandle) Record(ctx context.Context, value float64)

Record adds a new value to the list of measure's records.

func (Float64MeasureHandle) Release 

func (h Float64MeasureHandle) Release()

type GaugeOptionApplier 

type GaugeOptionApplier interface {
	// ApplyGaugeOption is used to make some general or
	// gauge-specific changes in the Options.
	ApplyGaugeOption(*Options)
}

GaugeOptionApplier is an interface for applying metric options that are valid only for gauge metrics.

type HandleImpl 

type HandleImpl interface {
	// RecordOne allows the SDK to observe a single metric event.
	RecordOne(ctx context.Context, number core.Number)

	// Release frees the resources associated with this handle. It
	// does not affect the metric this handle was created through.
	Release()
}

HandleImpl is the implementation-level interface to Set/Add/Record individual metrics with precomputed labels.

type InstrumentImpl 

type InstrumentImpl interface {
	// AcquireHandle creates a Handle to record metrics with
	// precomputed labels.
	AcquireHandle(labels LabelSet) HandleImpl

	// RecordOne allows the SDK to observe a single metric event.
	RecordOne(ctx context.Context, number core.Number, labels LabelSet)
}

InstrumentImpl is the implementation-level interface Set/Add/Record individual metrics without precomputed labels.

type Int64Counter 

type Int64Counter struct {
	// contains filtered or unexported fields
}

Int64Counter is a metric that accumulates int64 values.

func WrapInt64CounterInstrument 

func WrapInt64CounterInstrument(instrument InstrumentImpl) Int64Counter

WrapInt64CounterInstrument wraps the instrument in the type-safe wrapper as an integral counter.

It is mostly intended for SDKs.

func (*Int64Counter) AcquireHandle 

func (c *Int64Counter) AcquireHandle(labels LabelSet) (h Int64CounterHandle)

AcquireHandle creates a handle for this counter. The labels should contain the keys and values for each key specified in the counter with the WithKeys option.

If the labels do not contain a value for the key specified in the counter with the WithKeys option, then the missing value will be treated as unspecified.

func (*Int64Counter) Add 

func (c *Int64Counter) Add(ctx context.Context, value int64, labels LabelSet)

Add adds the value to the counter's sum. The labels should contain the keys and values for each key specified in the counter with the WithKeys option.

If the labels do not contain a value for the key specified in the counter with the WithKeys option, then the missing value will be treated as unspecified.

func (Int64Counter) Impl 

func (m Int64Counter) Impl() InstrumentImpl

func (*Int64Counter) Measurement 

func (c *Int64Counter) Measurement(value int64) Measurement

Measurement creates a Measurement object to use with batch recording.

type Int64CounterHandle 

type Int64CounterHandle struct {
	// contains filtered or unexported fields
}

Int64CounterHandle is a handle for Int64Counter.

It inherits the Release function from commonHandle.

func (*Int64CounterHandle) Add 

func (h *Int64CounterHandle) Add(ctx context.Context, value int64)

Add adds the value to the counter's sum.

func (Int64CounterHandle) Release 

func (h Int64CounterHandle) Release()

type Int64Gauge 

type Int64Gauge struct {
	// contains filtered or unexported fields
}

Int64Gauge is a metric that stores the last int64 value.

func WrapInt64GaugeInstrument 

func WrapInt64GaugeInstrument(instrument InstrumentImpl) Int64Gauge

WrapInt64GaugeInstrument wraps the instrument in the type-safe wrapper as an integral gauge.

It is mostly intended for SDKs.

func (*Int64Gauge) AcquireHandle 

func (g *Int64Gauge) AcquireHandle(labels LabelSet) (h Int64GaugeHandle)

AcquireHandle creates a handle for this gauge. The labels should contain the keys and values for each key specified in the gauge with the WithKeys option.

If the labels do not contain a value for the key specified in the gauge with the WithKeys option, then the missing value will be treated as unspecified.

func (Int64Gauge) Impl 

func (m Int64Gauge) Impl() InstrumentImpl

func (*Int64Gauge) Measurement 

func (g *Int64Gauge) Measurement(value int64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (*Int64Gauge) Set 

func (g *Int64Gauge) Set(ctx context.Context, value int64, labels LabelSet)

Set assigns the passed value to the value of the gauge. The labels should contain the keys and values for each key specified in the gauge with the WithKeys option.

If the labels do not contain a value for the key specified in the gauge with the WithKeys option, then the missing value will be treated as unspecified.

type Int64GaugeHandle 

type Int64GaugeHandle struct {
	// contains filtered or unexported fields
}

Int64GaugeHandle is a handle for Int64Gauge.

It inherits the Release function from commonHandle.

func (Int64GaugeHandle) Release 

func (h Int64GaugeHandle) Release()

func (*Int64GaugeHandle) Set 

func (h *Int64GaugeHandle) Set(ctx context.Context, value int64)

Set assigns the passed value to the value of the gauge.

type Int64Measure 

type Int64Measure struct {
	// contains filtered or unexported fields
}

Int64Measure is a metric that records int64 values.

func WrapInt64MeasureInstrument 

func WrapInt64MeasureInstrument(instrument InstrumentImpl) Int64Measure

WrapInt64MeasureInstrument wraps the instrument in the type-safe wrapper as an integral measure.

It is mostly intended for SDKs.

func (*Int64Measure) AcquireHandle 

func (c *Int64Measure) AcquireHandle(labels LabelSet) (h Int64MeasureHandle)

AcquireHandle creates a handle for this measure. The labels should contain the keys and values for each key specified in the measure with the WithKeys option.

If the labels do not contain a value for the key specified in the measure with the WithKeys option, then the missing value will be treated as unspecified.

func (Int64Measure) Impl 

func (m Int64Measure) Impl() InstrumentImpl

func (*Int64Measure) Measurement 

func (c *Int64Measure) Measurement(value int64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (*Int64Measure) Record 

func (c *Int64Measure) Record(ctx context.Context, value int64, labels LabelSet)

Record adds a new value to the list of measure's records. The labels should contain the keys and values for each key specified in the measure with the WithKeys option.

If the labels do not contain a value for the key specified in the measure with the WithKeys option, then the missing value will be treated as unspecified.

type Int64MeasureHandle 

type Int64MeasureHandle struct {
	// contains filtered or unexported fields
}

Int64MeasureHandle is a handle for Int64Measure.

It inherits the Release function from commonHandle.

func (*Int64MeasureHandle) Record 

func (h *Int64MeasureHandle) Record(ctx context.Context, value int64)

Record adds a new value to the list of measure's records.

func (Int64MeasureHandle) Release 

func (h Int64MeasureHandle) Release()

type LabelSet 

type LabelSet interface {
}

LabelSet is an implementation-level interface that represents a []core.KeyValue for use as pre-defined labels in the metrics API.

type MeasureOptionApplier 

type MeasureOptionApplier interface {
	// ApplyMeasureOption is used to make some general or
	// measure-specific changes in the Options.
	ApplyMeasureOption(*Options)
}

MeasureOptionApplier is an interface for applying metric options that are valid only for measure metrics.

func WithAbsolute 

func WithAbsolute(absolute bool) MeasureOptionApplier

WithAbsolute sets whether a measure is not permitted to be negative.

type Measurement 

type Measurement struct {
	// contains filtered or unexported fields
}

Measurement is used for reporting a batch of metric values. Instances of this type should be created by instruments (e.g., Int64Counter.Measurement()).

func (Measurement) InstrumentImpl 

func (m Measurement) InstrumentImpl() InstrumentImpl

Instrument returns the instrument that created this measurement. This returns an implementation-level object for use by the SDK, users should not refer to this.

func (Measurement) Number 

func (m Measurement) Number() core.Number

Number returns a number recorded in this measurement.

type Meter 

type Meter interface {
	// Labels returns a reference to a set of labels that cannot
	// be read by the application.
	Labels(...core.KeyValue) LabelSet

	// NewInt64Counter creates a new integral counter with a given
	// name and customized with passed options.
	NewInt64Counter(name string, cos ...CounterOptionApplier) Int64Counter
	// NewFloat64Counter creates a new floating point counter with
	// a given name and customized with passed options.
	NewFloat64Counter(name string, cos ...CounterOptionApplier) Float64Counter
	// NewInt64Gauge creates a new integral gauge with a given
	// name and customized with passed options.
	NewInt64Gauge(name string, gos ...GaugeOptionApplier) Int64Gauge
	// NewFloat64Gauge creates a new floating point gauge with a
	// given name and customized with passed options.
	NewFloat64Gauge(name string, gos ...GaugeOptionApplier) Float64Gauge
	// NewInt64Measure creates a new integral measure with a given
	// name and customized with passed options.
	NewInt64Measure(name string, mos ...MeasureOptionApplier) Int64Measure
	// NewFloat64Measure creates a new floating point measure with
	// a given name and customized with passed options.
	NewFloat64Measure(name string, mos ...MeasureOptionApplier) Float64Measure

	// RecordBatch atomically records a batch of measurements.
	RecordBatch(context.Context, LabelSet, ...Measurement)
}

Meter is an interface to the metrics portion of the OpenTelemetry SDK.

type NoopMeter 

type NoopMeter struct{}

func (NoopMeter) Labels 

func (NoopMeter) Labels(...core.KeyValue) LabelSet

func (NoopMeter) NewFloat64Counter 

func (NoopMeter) NewFloat64Counter(name string, cos ...CounterOptionApplier) Float64Counter

func (NoopMeter) NewFloat64Gauge 

func (NoopMeter) NewFloat64Gauge(name string, gos ...GaugeOptionApplier) Float64Gauge

func (NoopMeter) NewFloat64Measure 

func (NoopMeter) NewFloat64Measure(name string, mos ...MeasureOptionApplier) Float64Measure

func (NoopMeter) NewInt64Counter 

func (NoopMeter) NewInt64Counter(name string, cos ...CounterOptionApplier) Int64Counter

func (NoopMeter) NewInt64Gauge 

func (NoopMeter) NewInt64Gauge(name string, gos ...GaugeOptionApplier) Int64Gauge

func (NoopMeter) NewInt64Measure 

func (NoopMeter) NewInt64Measure(name string, mos ...MeasureOptionApplier) Int64Measure

func (NoopMeter) RecordBatch 

func (NoopMeter) RecordBatch(context.Context, LabelSet, ...Measurement)

type NoopProvider 

type NoopProvider struct{}

func (NoopProvider) Meter added in v0.2.0 

func (NoopProvider) Meter(name string) Meter

type Option 

type Option func(*Options)

Option supports specifying the various metric options.

type OptionApplier 

type OptionApplier interface {
	CounterOptionApplier
	GaugeOptionApplier
	MeasureOptionApplier
	// ApplyOption is used to make some general changes in the
	// Options.
	ApplyOption(*Options)
}

OptionApplier is an interface for applying metric options that are valid for all the kinds of metrics.

func WithDescription 

func WithDescription(desc string) OptionApplier

WithDescription applies provided description.

func WithKeys 

func WithKeys(keys ...core.Key) OptionApplier

WithKeys applies recommended label keys. Multiple `WithKeys` options accumulate.

func WithUnit 

func WithUnit(unit unit.Unit) OptionApplier

WithUnit applies provided unit.

type Options 

type Options struct {
	// Description is an optional field describing the metric
	// instrument.
	Description string
	// Unit is an optional field describing the metric instrument.
	Unit unit.Unit
	// Keys are recommended keys determined in the handles
	// obtained for the metric.
	Keys []core.Key
	// Alternate defines the property of metric value dependent on
	// a metric type.
	//
	// - for Counter, true implies that the metric is an up-down
	//   Counter
	//
	// - for Gauge, true implies that the metric is a
	//   non-descending Gauge
	//
	// - for Measure, true implies that the metric supports
	//   positive and negative values
	Alternate bool
}

Options contains some options for metrics of any kind.

type Provider 

type Provider interface {
	// Meter gets a named Meter interface.  If the name is an
	// empty string, the provider uses a default name.
	Meter(name string) Meter
}

Provider supports named Meter instances.

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.