package metric

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

metric package provides an API for reporting diagnostic measurements using four basic kinds of instruments.

The three basic kinds are:

- counters - measures - observers

All instruments report either float64 or int64 values.

The primary object that handles metrics is Meter. Meter can be obtained from Provider. The implementations of the Meter and Provider are provided by SDK. Normally, the Meter is used directly only for the instrument creation and batch recording.

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.

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.

Observers are instruments that are reporting a current state of a set of values. An example could be voltage or temperature. Observers can be created with either RegisterFloat64Observer or RegisterInt64Observer. Observers 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 Register*Observer function - this permits the reported values only to go up. Reporting of the new values happens asynchronously, with the use of a callback passed to the Register*Observer function. The callback can report multiple values. There is no unregister function.

Counters and measures 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, 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

Variables 

var ErrSDKReturnedNilImpl = errors.New("SDK returned a nil implementation")

Types

type AsyncImpl 

type AsyncImpl interface {
	InstrumentImpl
}

AsyncImpl is an implementation-level interface to an asynchronous instrument (e.g., Observer instruments).

type BoundFloat64Counter 

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

BoundFloat64Counter is a bound instrument for Float64Counter.

It inherits the Unbind function from syncBoundInstrument.

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 BoundFloat64Measure 

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

BoundFloat64Measure is a bound instrument for Float64Measure.

It inherits the Unbind function from syncBoundInstrument.

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 BoundInt64Counter 

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

BoundInt64Counter is a boundInstrument for Int64Counter.

It inherits the Unbind function from syncBoundInstrument.

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 BoundInt64Measure 

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

BoundInt64Measure is a bound instrument for Int64Measure.

It inherits the Unbind function from syncBoundInstrument.

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 BoundSyncImpl 

type BoundSyncImpl interface {

	// RecordOne captures a single synchronous 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()
}

BoundSyncImpl is the implementation-level interface to a generic bound synchronous instrument

type Config 

type Config 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
	// Resource describes the entity for which measurements are made.
	Resource resource.Resource
	// LibraryName is the name given to the Meter that created
	// this instrument.  See `Provider`.
	LibraryName string
}

Config contains some options for metrics of any kind.

func Configure 

func Configure(opts []Option) Config

Configure is a helper that applies all the options to a Config.

type Descriptor 

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

Descriptor contains all the settings that describe an instrument, including its name, metric kind, number kind, and the configurable options.

func NewDescriptor 

func NewDescriptor(name string, mkind Kind, nkind core.NumberKind, opts ...Option) Descriptor

NewDescriptor returns a Descriptor with the given contents.

func (Descriptor) Description 

func (d Descriptor) Description() string

Description provides a human-readable description of the metric instrument.

func (Descriptor) Keys 

func (d Descriptor) Keys() []core.Key

Keys returns the recommended keys included in the metric definition. These keys may be used by a Batcher as a default set of grouping keys for the metric instrument.

func (Descriptor) LibraryName 

func (d Descriptor) LibraryName() string

LibraryName returns the metric instrument's library name, typically given via a call to Provider.Meter().

func (Descriptor) MetricKind 

func (d Descriptor) MetricKind() Kind

MetricKind returns the specific kind of instrument.

func (Descriptor) Name 

func (d Descriptor) Name() string

Name returns the metric instrument's name.

func (Descriptor) NumberKind 

func (d Descriptor) NumberKind() core.NumberKind

NumberKind returns whether this instrument is declared over int64, float64, or uint64 values.

func (Descriptor) Resource 

func (d Descriptor) Resource() resource.Resource

Resource returns the Resource describing the entity for which the metric instrument measures.

func (Descriptor) Unit 

func (d Descriptor) Unit() unit.Unit

Unit describes the units of the metric instrument. Unitless metrics return the empty string.

type Float64Counter 

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

Float64Counter is a metric that accumulates float64 values.

func WrapFloat64CounterInstrument 

func WrapFloat64CounterInstrument(syncInst SyncImpl, err error) (Float64Counter, error)

WrapFloat64CounterInstrument returns an `Float64Counter` from a `SyncImpl`. An error will be generated if the `SyncImpl` is nil (in which case a No-op is substituted), otherwise the error passes through.

func (Float64Counter) Add 

func (c Float64Counter) Add(ctx context.Context, value float64, labels ...core.KeyValue)

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 ...core.KeyValue) (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) Measurement 

func (c Float64Counter) Measurement(value float64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (Float64Counter) SyncImpl 

func (s Float64Counter) SyncImpl() SyncImpl

type Float64Measure 

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

Float64Measure is a metric that records float64 values.

func WrapFloat64MeasureInstrument 

func WrapFloat64MeasureInstrument(syncInst SyncImpl, err error) (Float64Measure, error)

WrapFloat64MeasureInstrument returns an `Float64Measure` from a `SyncImpl`. An error will be generated if the `SyncImpl` is nil (in which case a No-op is substituted), otherwise the error passes through.

func (Float64Measure) Bind 

func (c Float64Measure) Bind(labels ...core.KeyValue) (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) 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 ...core.KeyValue)

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.

func (Float64Measure) SyncImpl 

func (s Float64Measure) SyncImpl() SyncImpl

type Float64Observer 

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

Float64Observer is a metric that captures a set of float64 values at a point in time.

func WrapFloat64ObserverInstrument 

func WrapFloat64ObserverInstrument(asyncInst AsyncImpl, err error) (Float64Observer, error)

WrapFloat64ObserverInstrument returns an `Float64Observer` from a `AsyncImpl`. An error will be generated if the `AsyncImpl` is nil (in which case a No-op is substituted), otherwise the error passes through.

func (Float64Observer) AsyncImpl 

func (a Float64Observer) AsyncImpl() AsyncImpl

type Float64ObserverCallback 

type Float64ObserverCallback func(result Float64ObserverResult)

Float64ObserverCallback is a type of callback that floating point observers run.

type Float64ObserverResult 

type Float64ObserverResult interface {
	Observe(value float64, labels ...core.KeyValue)
}

Float64ObserverResult is an interface for reporting floating point observations.

type InstrumentImpl 

type InstrumentImpl interface {
	// Implementation returns the underlying implementation of the
	// instrument, which allows the implementation to gain access
	// to its own representation especially from a `Measurement`.
	Implementation() interface{}

	// Descriptor returns a copy of the instrument's Descriptor.
	Descriptor() Descriptor
}

InstrumentImpl is a common interface for synchronous and asynchronous instruments.

type Int64Counter 

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

Int64Counter is a metric that accumulates int64 values.

func WrapInt64CounterInstrument 

func WrapInt64CounterInstrument(syncInst SyncImpl, err error) (Int64Counter, error)

WrapInt64CounterInstrument returns an `Int64Counter` from a `SyncImpl`. An error will be generated if the `SyncImpl` is nil (in which case a No-op is substituted), otherwise the error passes through.

func (Int64Counter) Add 

func (c Int64Counter) Add(ctx context.Context, value int64, labels ...core.KeyValue)

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 ...core.KeyValue) (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) Measurement 

func (c Int64Counter) Measurement(value int64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (Int64Counter) SyncImpl 

func (s Int64Counter) SyncImpl() SyncImpl

type Int64Measure 

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

Int64Measure is a metric that records int64 values.

func WrapInt64MeasureInstrument 

func WrapInt64MeasureInstrument(syncInst SyncImpl, err error) (Int64Measure, error)

WrapInt64MeasureInstrument returns an `Int64Measure` from a `SyncImpl`. An error will be generated if the `SyncImpl` is nil (in which case a No-op is substituted), otherwise the error passes through.

func (Int64Measure) Bind 

func (c Int64Measure) Bind(labels ...core.KeyValue) (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) 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 ...core.KeyValue)

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.

func (Int64Measure) SyncImpl 

func (s Int64Measure) SyncImpl() SyncImpl

type Int64Observer 

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

Int64Observer is a metric that captures a set of int64 values at a point in time.

func WrapInt64ObserverInstrument 

func WrapInt64ObserverInstrument(asyncInst AsyncImpl, err error) (Int64Observer, error)

WrapInt64ObserverInstrument returns an `Int64Observer` from a `AsyncImpl`. An error will be generated if the `AsyncImpl` is nil (in which case a No-op is substituted), otherwise the error passes through.

func (Int64Observer) AsyncImpl 

func (a Int64Observer) AsyncImpl() AsyncImpl

type Int64ObserverCallback 

type Int64ObserverCallback func(result Int64ObserverResult)

Int64ObserverCallback is a type of callback that integral observers run.

type Int64ObserverResult 

type Int64ObserverResult interface {
	Observe(value int64, labels ...core.KeyValue)
}

Int64ObserverResult is an interface for reporting integral observations.

type Kind 

type Kind int8

Kind describes the kind of instrument. 

const (
	// MeasureKind indicates a Measure instrument.
	MeasureKind Kind = iota
	// ObserverKind indicates an Observer instrument.
	ObserverKind
	// CounterKind indicates a Counter instrument.
	CounterKind
)

func (Kind) String 

func (i Kind) String() string

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

func (m Measurement) Number() core.Number

Number returns a number recorded in this measurement.

func (Measurement) SyncImpl 

func (m Measurement) SyncImpl() SyncImpl

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

type Meter 

type Meter interface {
	// RecordBatch atomically records a batch of measurements.
	RecordBatch(context.Context, []core.KeyValue, ...Measurement)

	// NewInt64Counter creates a new integral counter with a given
	// name and customized with passed options.
	NewInt64Counter(name string, opts ...Option) (Int64Counter, error)
	// NewFloat64Counter creates a new floating point counter with
	// a given name and customized with passed options.
	NewFloat64Counter(name string, opts ...Option) (Float64Counter, error)
	// NewInt64Measure creates a new integral measure with a given
	// name and customized with passed options.
	NewInt64Measure(name string, opts ...Option) (Int64Measure, error)
	// NewFloat64Measure creates a new floating point measure with
	// a given name and customized with passed options.
	NewFloat64Measure(name string, opts ...Option) (Float64Measure, error)

	// RegisterInt64Observer creates a new integral observer with a
	// given name, running a given callback, and customized with passed
	// options. Callback can be nil.
	RegisterInt64Observer(name string, callback Int64ObserverCallback, opts ...Option) (Int64Observer, error)
	// RegisterFloat64Observer creates a new floating point observer
	// with a given name, running a given callback, and customized with
	// passed options. Callback can be nil.
	RegisterFloat64Observer(name string, callback Float64ObserverCallback, opts ...Option) (Float64Observer, error)
}

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

func WrapMeterImpl 

func WrapMeterImpl(impl MeterImpl, libraryName string) Meter

WrapMeterImpl constructs a `Meter` implementation from a `MeterImpl` implementation.

type MeterImpl 

type MeterImpl interface {
	// RecordBatch atomically records a batch of measurements.
	RecordBatch(context.Context, []core.KeyValue, ...Measurement)

	// NewSyncInstrument returns a newly constructed
	// synchronous instrument implementation or an error, should
	// one occur.
	NewSyncInstrument(descriptor Descriptor) (SyncImpl, error)

	// NewAsyncInstrument returns a newly constructed
	// asynchronous instrument implementation or an error, should
	// one occur.
	NewAsyncInstrument(
		descriptor Descriptor,
		callback func(func(core.Number, []core.KeyValue)),
	) (AsyncImpl, error)
}

MeterImpl is a convenient interface for SDK and test implementations that would provide a `Meter` but do not wish to re-implement the API's type-safe interfaces. Helpers provided in this package will construct a `Meter` given a `MeterImpl`.

type MeterMust 

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

MeterMust is a wrapper for Meter interfaces that panics when any instrument constructor encounters an error.

func Must 

func Must(meter Meter) MeterMust

Must constructs a MeterMust implementation from a Meter, allowing the application to panic when any instrument constructor yields an error.

func (MeterMust) NewFloat64Counter 

func (mm MeterMust) NewFloat64Counter(name string, cos ...Option) Float64Counter

NewFloat64Counter calls `Meter.NewFloat64Counter` and returns the instrument, panicking if it encounters an error.

func (MeterMust) NewFloat64Measure 

func (mm MeterMust) NewFloat64Measure(name string, mos ...Option) Float64Measure

NewFloat64Measure calls `Meter.NewFloat64Measure` and returns the instrument, panicking if it encounters an error.

func (MeterMust) NewInt64Counter 

func (mm MeterMust) NewInt64Counter(name string, cos ...Option) Int64Counter

NewInt64Counter calls `Meter.NewInt64Counter` and returns the instrument, panicking if it encounters an error.

func (MeterMust) NewInt64Measure 

func (mm MeterMust) NewInt64Measure(name string, mos ...Option) Int64Measure

NewInt64Measure calls `Meter.NewInt64Measure` and returns the instrument, panicking if it encounters an error.

func (MeterMust) RegisterFloat64Observer 

func (mm MeterMust) RegisterFloat64Observer(name string, callback Float64ObserverCallback, oos ...Option) Float64Observer

RegisterFloat64Observer calls `Meter.RegisterFloat64Observer` and returns the instrument, panicking if it encounters an error.

func (MeterMust) RegisterInt64Observer 

func (mm MeterMust) RegisterInt64Observer(name string, callback Int64ObserverCallback, oos ...Option) Int64Observer

RegisterInt64Observer calls `Meter.RegisterInt64Observer` and returns the instrument, panicking if it encounters an error.

type NoopAsync 

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

func (NoopAsync) Descriptor 

func (NoopAsync) Descriptor() Descriptor

func (NoopAsync) Implementation 

func (NoopAsync) Implementation() interface{}

type NoopMeter 

type NoopMeter struct{}

func (NoopMeter) NewFloat64Counter 

func (NoopMeter) NewFloat64Counter(string, ...Option) (Float64Counter, error)

func (NoopMeter) NewFloat64Measure 

func (NoopMeter) NewFloat64Measure(string, ...Option) (Float64Measure, error)

func (NoopMeter) NewInt64Counter 

func (NoopMeter) NewInt64Counter(string, ...Option) (Int64Counter, error)

func (NoopMeter) NewInt64Measure 

func (NoopMeter) NewInt64Measure(string, ...Option) (Int64Measure, error)

func (NoopMeter) RecordBatch 

func (NoopMeter) RecordBatch(context.Context, []core.KeyValue, ...Measurement)

func (NoopMeter) RegisterFloat64Observer 

func (NoopMeter) RegisterFloat64Observer(string, Float64ObserverCallback, ...Option) (Float64Observer, error)

func (NoopMeter) RegisterInt64Observer 

func (NoopMeter) RegisterInt64Observer(string, Int64ObserverCallback, ...Option) (Int64Observer, error)

type NoopProvider 

type NoopProvider struct{}

func (NoopProvider) Meter 

func (NoopProvider) Meter(name string) Meter

type NoopSync 

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

func (NoopSync) Bind 

func (NoopSync) Bind([]core.KeyValue) BoundSyncImpl

func (NoopSync) Descriptor 

func (NoopSync) Descriptor() Descriptor

func (NoopSync) Implementation 

func (NoopSync) Implementation() interface{}

func (NoopSync) RecordOne 

func (NoopSync) RecordOne(context.Context, core.Number, []core.KeyValue)

type Option 

type Option interface {
	// Apply is used to set the Option value of a Config.
	Apply(*Config)
}

Option is an interface for applying metric options.

func WithDescription 

func WithDescription(desc string) Option

WithDescription applies provided description.

func WithKeys 

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

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

func WithLibraryName 

func WithLibraryName(name string) Option

WithLibraryName applies provided library name. This is meant for use in `Provider` implementations that have not used `WrapMeterImpl`. Implementations built using `WrapMeterImpl` have instrument descriptors taken care of through this package.

This option will have no effect when supplied by the user. Provider implementations are expected to append this option after the user-supplied options when building instrument descriptors.

func WithResource 

func WithResource(r resource.Resource) Option

WithResource applies provided Resource.

This will override any existing Resource.

func WithUnit 

func WithUnit(unit unit.Unit) Option

WithUnit applies provided unit.

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.

type Resourcer 

type Resourcer interface {
	Resource() resource.Resource
}

Resourcer is implemented by any value that has a Resource method, which returns the Resource associated with the value. The Resource method is used to set the Resource for Descriptors of new metric instruments.

type SyncImpl 

type SyncImpl interface {
	InstrumentImpl

	// Bind creates an implementation-level bound instrument,
	// binding a label set with this instrument implementation.
	Bind(labels []core.KeyValue) BoundSyncImpl

	// RecordOne captures a single synchronous metric event.
	RecordOne(ctx context.Context, number core.Number, labels []core.KeyValue)
}

SyncImpl is the implementation-level interface to a generic synchronous instrument (e.g., Measure and Counter instruments).

Source Files

api.go common.go counter.go doc.go kind_string.go measure.go must.go noop.go observer.go sdkhelpers.go

Directories

PathSynopsis
api/metric/registry
Version
v0.4.1
Published
Mar 31, 2020
Platform
darwin/amd64
Imports
6 packages
Last checked
26 minutes ago –

Tools for package owners.