instrument

package
v1.15.0-rc.2 Latest Latest
Warning

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

 Go to latest Published: Mar 23, 2023 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Overview

Package instrument provides the OpenTelemetry API instruments used to make measurements.

Each instrument is designed to make measurements of a particular type. Broadly, all instruments fall into two overlapping logical categories: asynchronous or synchronous, and int64 or float64.

All synchronous instruments (Int64Counter, Int64UpDownCounter, Int64Histogram, Float64Counter, Float64UpDownCounter, Float64Histogram) are used to measure the operation and performance of source code during the source code execution. These instruments only make measurements when the source code they instrument is run.

All asynchronous instruments (Int64ObservableCounter, Int64ObservableUpDownCounter, Int64ObservableGauge, Float64ObservableCounter, Float64ObservableUpDownCounter, Float64ObservableGauge) are used to measure metrics outside of the execution of source code. They are said to make "observations" via a callback function called once every measurement collection cycle.

Each instrument is also grouped by the value type it measures. Either int64 or float64. The value being measured will dictate which instrument in these categories to use.

Outside of these two broad categories, instruments are described by the function they are designed to serve. All Counters (Int64Counter, Float64Counter, Int64ObservableCounter, Float64ObservableCounter) are designed to measure values that never decrease in value, but instead only incrementally increase in value. UpDownCounters (Int64UpDownCounter, Float64UpDownCounter, Int64ObservableUpDownCounter, Float64ObservableUpDownCounter) on the other hand, are designed to measure values that can increase and decrease. When more information needs to be conveyed about all the synchronous measurements made during a collection cycle, a Histogram (Int64Histogram, Float64Histogram) should be used. Finally, when just the most recent measurement needs to be conveyed about an asynchronous measurement, a Gauge (Int64ObservableGauge, Float64ObservableGauge) should be used.

See the OpenTelemetry documentation for more information about instruments and their intended use.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Float64Callback added in v0.35.0 

type Float64Callback func(context.Context, Float64Observer) error

Float64Callback is a function registered with a Meter that makes observations for a Float64Observerable instrument it is registered with. Calls to the Float64Observer record measurement values for the Float64Observable.

The function needs to complete in a finite amount of time and the deadline of the passed context is expected to be honored.

The function needs to make unique observations across all registered Float64Callbacks. Meaning, it should not report measurements with the same attributes as another Float64Callbacks also registered for the same instrument.

The function needs to be concurrent safe.

type Float64Counter added in v0.35.0 

type Float64Counter interface {
	// Add records a change to the counter.
	Add(ctx context.Context, incr float64, attrs ...attribute.KeyValue)
}

Float64Counter is an instrument that records increasing float64 values.

Warning: methods may be added to this interface in minor releases.

type Float64CounterConfig added in v0.38.0 

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

Float64CounterConfig contains options for synchronous counter instruments that record int64 values.

func NewFloat64CounterConfig added in v0.38.0 

func NewFloat64CounterConfig(opts ...Float64CounterOption) Float64CounterConfig

NewFloat64CounterConfig returns a new Float64CounterConfig with all opts applied.

func (Float64CounterConfig) Description 

func (c Float64CounterConfig) Description() string

Description returns the configured description.

func (Float64CounterConfig) Unit 

func (c Float64CounterConfig) Unit() string

Unit returns the configured unit.

type Float64CounterOption added in v0.38.0 

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

Float64CounterOption applies options to a Float64CounterConfig. See Option for other options that can be used as a Float64CounterOption.

type Float64Histogram added in v0.35.0 

type Float64Histogram interface {
	// Record adds an additional value to the distribution.
	Record(ctx context.Context, incr float64, attrs ...attribute.KeyValue)
}

Float64Histogram is an instrument that records a distribution of float64 values.

Warning: methods may be added to this interface in minor releases.

type Float64HistogramConfig added in v0.38.0 

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

Float64HistogramConfig contains options for synchronous counter instruments that record int64 values.

func NewFloat64HistogramConfig added in v0.38.0 

func NewFloat64HistogramConfig(opts ...Float64HistogramOption) Float64HistogramConfig

NewFloat64HistogramConfig returns a new Float64HistogramConfig with all opts applied.

func (Float64HistogramConfig) Description 

func (c Float64HistogramConfig) Description() string

Description returns the configured description.

func (Float64HistogramConfig) Unit 

func (c Float64HistogramConfig) Unit() string

Unit returns the configured unit.

type Float64HistogramOption added in v0.38.0 

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

Float64HistogramOption applies options to a Float64HistogramConfig. See Option for other options that can be used as a Float64HistogramOption.

type Float64Observable added in v0.35.0 

type Float64Observable interface {
	Observable
	// contains filtered or unexported methods
}

Float64Observable describes a set of instruments used asynchronously to record float64 measurements once per collection cycle. Observations of these instruments are only made within a callback.

Warning: methods may be added to this interface in minor releases.

type Float64ObservableCounter added in v0.35.0 

type Float64ObservableCounter interface{ Float64Observable }

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

Warning: methods may be added to this interface in minor releases.

type Float64ObservableCounterConfig added in v0.38.0 

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

Float64ObservableCounterConfig contains options for asynchronous counter instruments that record int64 values.

func NewFloat64ObservableCounterConfig added in v0.38.0 

func NewFloat64ObservableCounterConfig(opts ...Float64ObservableCounterOption) Float64ObservableCounterConfig

NewFloat64ObservableCounterConfig returns a new Float64ObservableCounterConfig with all opts applied.

func (Float64ObservableCounterConfig) Callbacks 

func (c Float64ObservableCounterConfig) Callbacks() []Float64Callback

Callbacks returns the configured callbacks.

func (Float64ObservableCounterConfig) Description 

func (c Float64ObservableCounterConfig) Description() string

Description returns the configured description.

func (Float64ObservableCounterConfig) Unit 

func (c Float64ObservableCounterConfig) Unit() string

Unit returns the configured unit.

type Float64ObservableCounterOption added in v0.38.0 

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

Float64ObservableCounterOption applies options to a Float64ObservableCounterConfig. See Float64ObservableOption and Option for other options that can be used as a Float64ObservableCounterOption.

type Float64ObservableGauge added in v0.35.0 

type Float64ObservableGauge interface{ Float64Observable }

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

Warning: methods may be added to this interface in minor releases.

type Float64ObservableGaugeConfig added in v0.38.0 

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

Float64ObservableGaugeConfig contains options for asynchronous counter instruments that record int64 values.

func NewFloat64ObservableGaugeConfig added in v0.38.0 

func NewFloat64ObservableGaugeConfig(opts ...Float64ObservableGaugeOption) Float64ObservableGaugeConfig

NewFloat64ObservableGaugeConfig returns a new Float64ObservableGaugeConfig with all opts applied.

func (Float64ObservableGaugeConfig) Callbacks 

func (c Float64ObservableGaugeConfig) Callbacks() []Float64Callback

Callbacks returns the configured callbacks.

func (Float64ObservableGaugeConfig) Description 

func (c Float64ObservableGaugeConfig) Description() string

Description returns the configured description.

func (Float64ObservableGaugeConfig) Unit 

func (c Float64ObservableGaugeConfig) Unit() string

Unit returns the configured unit.

type Float64ObservableGaugeOption added in v0.38.0 

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

Float64ObservableGaugeOption applies options to a Float64ObservableGaugeConfig. See Float64ObservableOption and Option for other options that can be used as a Float64ObservableGaugeOption.

type Float64ObservableOption added in v0.38.0 

type Float64ObservableOption interface {
	Float64ObservableCounterOption
	Float64ObservableUpDownCounterOption
	Float64ObservableGaugeOption
}

Float64ObservableOption applies options to float64 Observer instruments.

func WithFloat64Callback added in v0.35.0 

func WithFloat64Callback(callback Float64Callback) Float64ObservableOption

WithFloat64Callback adds callback to be called for an instrument.

type Float64ObservableUpDownCounter added in v0.35.0 

type Float64ObservableUpDownCounter interface{ Float64Observable }

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

Warning: methods may be added to this interface in minor releases.

type Float64ObservableUpDownCounterConfig added in v0.38.0 

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

Float64ObservableUpDownCounterConfig contains options for asynchronous counter instruments that record int64 values.

func NewFloat64ObservableUpDownCounterConfig added in v0.38.0 

func NewFloat64ObservableUpDownCounterConfig(opts ...Float64ObservableUpDownCounterOption) Float64ObservableUpDownCounterConfig

NewFloat64ObservableUpDownCounterConfig returns a new Float64ObservableUpDownCounterConfig with all opts applied.

func (Float64ObservableUpDownCounterConfig) Callbacks 

func (c Float64ObservableUpDownCounterConfig) Callbacks() []Float64Callback

Callbacks returns the configured callbacks.

func (Float64ObservableUpDownCounterConfig) Description 

func (c Float64ObservableUpDownCounterConfig) Description() string

Description returns the configured description.

func (Float64ObservableUpDownCounterConfig) Unit 

func (c Float64ObservableUpDownCounterConfig) Unit() string

Unit returns the configured unit.

type Float64ObservableUpDownCounterOption added in v0.38.0 

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

Float64ObservableUpDownCounterOption applies options to a Float64ObservableUpDownCounterConfig. See Float64ObservableOption and Option for other options that can be used as a Float64ObservableUpDownCounterOption.

type Float64Observer added in v0.35.0 

type Float64Observer interface {
	// Observe records the float64 value with attributes.
	Observe(value float64, attributes ...attribute.KeyValue)
}

Float64Observer is a recorder of float64 measurements.

Warning: methods may be added to this interface in minor releases.

type Float64UpDownCounter added in v0.35.0 

type Float64UpDownCounter interface {
	// Add records a change to the counter.
	Add(ctx context.Context, incr float64, attrs ...attribute.KeyValue)
}

Float64UpDownCounter is an instrument that records increasing or decreasing float64 values.

Warning: methods may be added to this interface in minor releases.

type Float64UpDownCounterConfig added in v0.38.0 

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

Float64UpDownCounterConfig contains options for synchronous counter instruments that record int64 values.

func NewFloat64UpDownCounterConfig added in v0.38.0 

func NewFloat64UpDownCounterConfig(opts ...Float64UpDownCounterOption) Float64UpDownCounterConfig

NewFloat64UpDownCounterConfig returns a new Float64UpDownCounterConfig with all opts applied.

func (Float64UpDownCounterConfig) Description 

func (c Float64UpDownCounterConfig) Description() string

Description returns the configured description.

func (Float64UpDownCounterConfig) Unit 

func (c Float64UpDownCounterConfig) Unit() string

Unit returns the configured unit.

type Float64UpDownCounterOption added in v0.38.0 

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

Float64UpDownCounterOption applies options to a Float64UpDownCounterConfig. See Option for other options that can be used as a Float64UpDownCounterOption.

type Int64Callback added in v0.35.0 

type Int64Callback func(context.Context, Int64Observer) error

Int64Callback is a function registered with a Meter that makes observations for an Int64Observerable instrument it is registered with. Calls to the Int64Observer record measurement values for the Int64Observable.

The function needs to complete in a finite amount of time and the deadline of the passed context is expected to be honored.

The function needs to make unique observations across all registered Int64Callbacks. Meaning, it should not report measurements with the same attributes as another Int64Callbacks also registered for the same instrument.

The function needs to be concurrent safe.

type Int64Counter added in v0.35.0 

type Int64Counter interface {
	// Add records a change to the counter.
	Add(ctx context.Context, incr int64, attrs ...attribute.KeyValue)
}

Int64Counter is an instrument that records increasing int64 values.

Warning: methods may be added to this interface in minor releases.

type Int64CounterConfig added in v0.38.0 

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

Int64CounterConfig contains options for synchronous counter instruments that record int64 values.

func NewInt64CounterConfig added in v0.38.0 

func NewInt64CounterConfig(opts ...Int64CounterOption) Int64CounterConfig

NewInt64CounterConfig returns a new Int64CounterConfig with all opts applied.

func (Int64CounterConfig) Description 

func (c Int64CounterConfig) Description() string

Description returns the configured description.

func (Int64CounterConfig) Unit 

func (c Int64CounterConfig) Unit() string

Unit returns the configured unit.

type Int64CounterOption added in v0.38.0 

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

Int64CounterOption applies options to a Int64CounterConfig. See Option for other options that can be used as an Int64CounterOption.

type Int64Histogram added in v0.35.0 

type Int64Histogram interface {
	// Record adds an additional value to the distribution.
	Record(ctx context.Context, incr int64, attrs ...attribute.KeyValue)
}

Int64Histogram is an instrument that records a distribution of int64 values.

Warning: methods may be added to this interface in minor releases.

type Int64HistogramConfig added in v0.38.0 

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

Int64HistogramConfig contains options for synchronous counter instruments that record int64 values.

func NewInt64HistogramConfig added in v0.38.0 

func NewInt64HistogramConfig(opts ...Int64HistogramOption) Int64HistogramConfig

NewInt64HistogramConfig returns a new Int64HistogramConfig with all opts applied.

func (Int64HistogramConfig) Description 

func (c Int64HistogramConfig) Description() string

Description returns the configured description.

func (Int64HistogramConfig) Unit 

func (c Int64HistogramConfig) Unit() string

Unit returns the configured unit.

type Int64HistogramOption added in v0.38.0 

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

Int64HistogramOption applies options to a Int64HistogramConfig. See Option for other options that can be used as an Int64HistogramOption.

type Int64Observable added in v0.35.0 

type Int64Observable interface {
	Observable
	// contains filtered or unexported methods
}

Int64Observable describes a set of instruments used asynchronously to record int64 measurements once per collection cycle. Observations of these instruments are only made within a callback.

Warning: methods may be added to this interface in minor releases.

type Int64ObservableCounter added in v0.35.0 

type Int64ObservableCounter interface{ Int64Observable }

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

Warning: methods may be added to this interface in minor releases.

type Int64ObservableCounterConfig added in v0.38.0 

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

Int64ObservableCounterConfig contains options for asynchronous counter instruments that record int64 values.

func NewInt64ObservableCounterConfig added in v0.38.0 

func NewInt64ObservableCounterConfig(opts ...Int64ObservableCounterOption) Int64ObservableCounterConfig

NewInt64ObservableCounterConfig returns a new Int64ObservableCounterConfig with all opts applied.

func (Int64ObservableCounterConfig) Callbacks 

func (c Int64ObservableCounterConfig) Callbacks() []Int64Callback

Callbacks returns the configured callbacks.

func (Int64ObservableCounterConfig) Description 

func (c Int64ObservableCounterConfig) Description() string

Description returns the configured description.

func (Int64ObservableCounterConfig) Unit 

func (c Int64ObservableCounterConfig) Unit() string

Unit returns the configured unit.

type Int64ObservableCounterOption added in v0.38.0 

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

Int64ObservableCounterOption applies options to a Int64ObservableCounterConfig. See Int64ObservableOption and Option for other options that can be used as an Int64ObservableCounterOption.

type Int64ObservableGauge added in v0.35.0 

type Int64ObservableGauge interface{ Int64Observable }

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

Warning: methods may be added to this interface in minor releases.

type Int64ObservableGaugeConfig added in v0.38.0 

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

Int64ObservableGaugeConfig contains options for asynchronous counter instruments that record int64 values.

func NewInt64ObservableGaugeConfig added in v0.38.0 

func NewInt64ObservableGaugeConfig(opts ...Int64ObservableGaugeOption) Int64ObservableGaugeConfig

NewInt64ObservableGaugeConfig returns a new Int64ObservableGaugeConfig with all opts applied.

func (Int64ObservableGaugeConfig) Callbacks 

func (c Int64ObservableGaugeConfig) Callbacks() []Int64Callback

Callbacks returns the configured callbacks.

func (Int64ObservableGaugeConfig) Description 

func (c Int64ObservableGaugeConfig) Description() string

Description returns the configured description.

func (Int64ObservableGaugeConfig) Unit 

func (c Int64ObservableGaugeConfig) Unit() string

Unit returns the configured unit.

type Int64ObservableGaugeOption added in v0.38.0 

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

Int64ObservableGaugeOption applies options to a Int64ObservableGaugeConfig. See Int64ObservableOption and Option for other options that can be used as an Int64ObservableGaugeOption.

type Int64ObservableOption added in v0.38.0 

type Int64ObservableOption interface {
	Int64ObservableCounterOption
	Int64ObservableUpDownCounterOption
	Int64ObservableGaugeOption
}

Int64ObservableOption applies options to int64 Observer instruments.

func WithInt64Callback added in v0.35.0 

func WithInt64Callback(callback Int64Callback) Int64ObservableOption

WithInt64Callback adds callback to be called for an instrument.

type Int64ObservableUpDownCounter added in v0.35.0 

type Int64ObservableUpDownCounter interface{ Int64Observable }

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

Warning: methods may be added to this interface in minor releases.

type Int64ObservableUpDownCounterConfig added in v0.38.0 

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

Int64ObservableUpDownCounterConfig contains options for asynchronous counter instruments that record int64 values.

func NewInt64ObservableUpDownCounterConfig added in v0.38.0 

func NewInt64ObservableUpDownCounterConfig(opts ...Int64ObservableUpDownCounterOption) Int64ObservableUpDownCounterConfig

NewInt64ObservableUpDownCounterConfig returns a new Int64ObservableUpDownCounterConfig with all opts applied.

func (Int64ObservableUpDownCounterConfig) Callbacks 

func (c Int64ObservableUpDownCounterConfig) Callbacks() []Int64Callback

Callbacks returns the configured callbacks.

func (Int64ObservableUpDownCounterConfig) Description 

func (c Int64ObservableUpDownCounterConfig) Description() string

Description returns the configured description.

func (Int64ObservableUpDownCounterConfig) Unit 

func (c Int64ObservableUpDownCounterConfig) Unit() string

Unit returns the configured unit.

type Int64ObservableUpDownCounterOption added in v0.38.0 

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

Int64ObservableUpDownCounterOption applies options to a Int64ObservableUpDownCounterConfig. See Int64ObservableOption and Option for other options that can be used as an Int64ObservableUpDownCounterOption.

type Int64Observer added in v0.35.0 

type Int64Observer interface {
	// Observe records the int64 value with attributes.
	Observe(value int64, attributes ...attribute.KeyValue)
}

Int64Observer is a recorder of int64 measurements.

Warning: methods may be added to this interface in minor releases.

type Int64UpDownCounter added in v0.35.0 

type Int64UpDownCounter interface {
	// Add records a change to the counter.
	Add(ctx context.Context, incr int64, attrs ...attribute.KeyValue)
}

Int64UpDownCounter is an instrument that records increasing or decreasing int64 values.

Warning: methods may be added to this interface in minor releases.

type Int64UpDownCounterConfig added in v0.38.0 

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

Int64UpDownCounterConfig contains options for synchronous counter instruments that record int64 values.

func NewInt64UpDownCounterConfig added in v0.38.0 

func NewInt64UpDownCounterConfig(opts ...Int64UpDownCounterOption) Int64UpDownCounterConfig

NewInt64UpDownCounterConfig returns a new Int64UpDownCounterConfig with all opts applied.

func (Int64UpDownCounterConfig) Description 

func (c Int64UpDownCounterConfig) Description() string

Description returns the configured description.

func (Int64UpDownCounterConfig) Unit 

func (c Int64UpDownCounterConfig) Unit() string

Unit returns the configured unit.

type Int64UpDownCounterOption added in v0.38.0 

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

Int64UpDownCounterOption applies options to a Int64UpDownCounterConfig. See Option for other options that can be used as an Int64UpDownCounterOption.

type Observable added in v0.38.0 

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

Observable is used as a grouping mechanism for all instruments that are updated within a Callback.

type Option 

type Option interface {
	Int64CounterOption
	Int64UpDownCounterOption
	Int64HistogramOption
	Int64ObservableCounterOption
	Int64ObservableUpDownCounterOption
	Int64ObservableGaugeOption

	Float64CounterOption
	Float64UpDownCounterOption
	Float64HistogramOption
	Float64ObservableCounterOption
	Float64ObservableUpDownCounterOption
	Float64ObservableGaugeOption
}

Option applies options to all instruments.

func WithDescription 

func WithDescription(desc string) Option

WithDescription sets the instrument description.

func WithUnit 

func WithUnit(u string) Option

WithUnit sets the instrument unit.

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.