otel: go.opentelemetry.io/otel/api/metric Index | Files

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

Package Files

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

func ApplyCounterOptions Uses

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

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

func ApplyGaugeOptions Uses

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

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

func ApplyMeasureOptions Uses

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

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

type BoundFloat64Counter Uses

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 Uses

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

Add adds the value to the counter's sum.

func (BoundFloat64Counter) Unbind Uses

func (h BoundFloat64Counter) Unbind()

type BoundFloat64Gauge Uses

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 Uses

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

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

func (BoundFloat64Gauge) Unbind Uses

func (h BoundFloat64Gauge) Unbind()

type BoundFloat64Measure Uses

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 Uses

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

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

func (BoundFloat64Measure) Unbind Uses

func (h BoundFloat64Measure) Unbind()

type BoundInstrumentImpl Uses

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 Uses

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

BoundInt64Counter is a boundInstrument for Int64Counter.

It inherits the Unbind function from commonBoundInstrument.

func (BoundInt64Counter) Add Uses

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

Add adds the value to the counter's sum.

func (BoundInt64Counter) Unbind Uses

func (h BoundInt64Counter) Unbind()

type BoundInt64Gauge Uses

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 Uses

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

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

func (BoundInt64Gauge) Unbind Uses

func (h BoundInt64Gauge) Unbind()

type BoundInt64Measure Uses

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 Uses

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

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

func (BoundInt64Measure) Unbind Uses

func (h BoundInt64Measure) Unbind()

type CounterGaugeOptionApplier Uses

type CounterGaugeOptionApplier interface {
    CounterOptionApplier
    GaugeOptionApplier
}

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

func WithMonotonic Uses

func WithMonotonic(monotonic bool) CounterGaugeOptionApplier

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

type CounterOptionApplier Uses

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 Uses

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

Float64Counter is a metric that accumulates float64 values.

func WrapFloat64CounterInstrument Uses

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 Uses

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 Uses

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 Uses

func (m Float64Counter) Impl() InstrumentImpl

func (Float64Counter) Measurement Uses

func (c Float64Counter) Measurement(value float64) Measurement

Measurement creates a Measurement object to use with batch recording.

type Float64Gauge Uses

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

Float64Gauge is a metric that stores the last float64 value.

func WrapFloat64GaugeInstrument Uses

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 Uses

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 Uses

func (m Float64Gauge) Impl() InstrumentImpl

func (Float64Gauge) Measurement Uses

func (g Float64Gauge) Measurement(value float64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (Float64Gauge) Set Uses

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 Uses

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

Float64Measure is a metric that records float64 values.

func WrapFloat64MeasureInstrument Uses

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 Uses

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 Uses

func (m Float64Measure) Impl() InstrumentImpl

func (Float64Measure) Measurement Uses

func (c Float64Measure) Measurement(value float64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (Float64Measure) Record Uses

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 Uses

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 Uses

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 Uses

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

Int64Counter is a metric that accumulates int64 values.

func WrapInt64CounterInstrument Uses

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 Uses

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 Uses

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 Uses

func (m Int64Counter) Impl() InstrumentImpl

func (Int64Counter) Measurement Uses

func (c Int64Counter) Measurement(value int64) Measurement

Measurement creates a Measurement object to use with batch recording.

type Int64Gauge Uses

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

Int64Gauge is a metric that stores the last int64 value.

func WrapInt64GaugeInstrument Uses

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 Uses

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 Uses

func (m Int64Gauge) Impl() InstrumentImpl

func (Int64Gauge) Measurement Uses

func (g Int64Gauge) Measurement(value int64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (Int64Gauge) Set Uses

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 Uses

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

Int64Measure is a metric that records int64 values.

func WrapInt64MeasureInstrument Uses

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 Uses

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 Uses

func (m Int64Measure) Impl() InstrumentImpl

func (Int64Measure) Measurement Uses

func (c Int64Measure) Measurement(value int64) Measurement

Measurement creates a Measurement object to use with batch recording.

func (Int64Measure) Record Uses

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 Uses

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 Uses

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 Uses

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 Uses

func WithAbsolute(absolute bool) MeasureOptionApplier

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

type Measurement Uses

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 Uses

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 Uses

func (m Measurement) Number() core.Number

Number returns a number recorded in this measurement.

type Meter Uses

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 Uses

type NoopMeter struct{}

func (NoopMeter) Labels Uses

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

func (NoopMeter) NewFloat64Counter Uses

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

func (NoopMeter) NewFloat64Gauge Uses

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

func (NoopMeter) NewFloat64Measure Uses

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

func (NoopMeter) NewInt64Counter Uses

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

func (NoopMeter) NewInt64Gauge Uses

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

func (NoopMeter) NewInt64Measure Uses

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

func (NoopMeter) RecordBatch Uses

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

type NoopProvider Uses

type NoopProvider struct{}

func (NoopProvider) Meter Uses

func (NoopProvider) Meter(name string) Meter

type Option Uses

type Option func(*Options)

Option supports specifying the various metric options.

type OptionApplier Uses

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 Uses

func WithDescription(desc string) OptionApplier

WithDescription applies provided description.

func WithKeys Uses

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

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

func WithUnit Uses

func WithUnit(unit unit.Unit) OptionApplier

WithUnit applies provided unit.

type Options Uses

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 Uses

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.

Package metric imports 3 packages (graph) and is imported by 9 packages. Updated 2020-02-05. Refresh now. Tools for package owners.