package metric

import "go.opentelemetry.io/otel/api/metric"

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 bound instrument 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 bound instruments for a potentially more efficient reporting. The bound instruments have the same function names as the instruments (so a Counter bound instrument has Add, a Gauge bound instrument has Set, and a Measure bound instrument has Record). Bound Instruments can be created with the Bind function of the respective instrument. When done with the bound instrument, call Unbind on it.

Index

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 BoundFloat64Counter 

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

BoundFloat64Counter is a bound instrument for Float64Counter.

It inherits the Unbind function from commonBoundInstrument.

func (BoundFloat64Counter) Add 

func (b BoundFloat64Counter) Add(ctx context.Context, value float64)

Add adds the value to the counter's sum.

func (BoundFloat64Counter) Unbind 

func (h BoundFloat64Counter) Unbind()

type BoundFloat64Gauge 

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

BoundFloat64Gauge is a bound instrument for Float64Gauge.

It inherits the Unbind function from commonBoundInstrument.

func (BoundFloat64Gauge) Set 

func (b BoundFloat64Gauge) Set(ctx context.Context, value float64)

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

func (BoundFloat64Gauge) Unbind 

func (h BoundFloat64Gauge) Unbind()

type BoundFloat64Measure 

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

BoundFloat64Measure is a bound instrument for Float64Measure.

It inherits the Unbind function from commonBoundInstrument.

func (BoundFloat64Measure) Record 

func (b BoundFloat64Measure) Record(ctx context.Context, value float64)

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

func (BoundFloat64Measure) Unbind 

func (h BoundFloat64Measure) Unbind()

type BoundInstrumentImpl 

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

	// Unbind frees the resources associated with this bound instrument. It
	// does not affect the metric this bound instrument was created through.
	Unbind()
}

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

type BoundInt64Counter 

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

BoundInt64Counter is a boundInstrument for Int64Counter.

It inherits the Unbind function from commonBoundInstrument.

func (BoundInt64Counter) Add 

func (b BoundInt64Counter) Add(ctx context.Context, value int64)

Add adds the value to the counter's sum.

func (BoundInt64Counter) Unbind 

func (h BoundInt64Counter) Unbind()

type BoundInt64Gauge 

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

BoundInt64Gauge is a bound instrument for Int64Gauge.

It inherits the Unbind function from commonBoundInstrument.

func (BoundInt64Gauge) Set 

func (b BoundInt64Gauge) Set(ctx context.Context, value int64)

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

func (BoundInt64Gauge) Unbind 

func (h BoundInt64Gauge) Unbind()

type BoundInt64Measure 

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

BoundInt64Measure is a bound instrument for Int64Measure.

It inherits the Unbind function from commonBoundInstrument.

func (BoundInt64Measure) Record 

func (b BoundInt64Measure) Record(ctx context.Context, value int64)

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

func (BoundInt64Measure) Unbind 

func (h BoundInt64Measure) Unbind()

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) 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) Bind 

func (c Float64Counter) Bind(labels LabelSet) (h BoundFloat64Counter)

Bind creates a bound instrument 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) 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 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) Bind 

func (g Float64Gauge) Bind(labels LabelSet) (h BoundFloat64Gauge)

Bind creates a bound instrument 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 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) Bind 

func (c Float64Measure) Bind(labels LabelSet) (h BoundFloat64Measure)

Bind creates a bound instrument 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 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 InstrumentImpl 

type InstrumentImpl interface {
	// Bind creates a Bound Instrument to record metrics with
	// precomputed labels.
	Bind(labels LabelSet) BoundInstrumentImpl

	// 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) 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) Bind 

func (c Int64Counter) Bind(labels LabelSet) (h BoundInt64Counter)

Bind creates a bound instrument 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) 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 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) Bind 

func (g Int64Gauge) Bind(labels LabelSet) (h BoundInt64Gauge)

Bind creates a bound instrument 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 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) Bind 

func (c Int64Measure) Bind(labels LabelSet) (h BoundInt64Measure)

Bind creates a bound instrument 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 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 LabelSetDelegate 

type LabelSetDelegate interface {
	Delegate() LabelSet
}

LabelSetDelegate is a general-purpose delegating implementation of the LabelSet interface. This is implemented by the default Provider returned by api/global.SetMeterProvider(), and should be tested for by implementations before converting a LabelSet to their private concrete type.

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 

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

api.go common.go counter.go doc.go gauge.go measure.go noop.go sdkhelpers.go

Version
v0.2.2
Published
Feb 27, 2020
Platform
darwin/amd64
Imports
3 packages
Last checked
26 minutes ago –

Tools for package owners.