metric

package module
v1.33.0 Latest Latest
Warning

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

 Go to latest Published: Dec 12, 2024 License: Apache-2.0 Imports: 3 Imported by: 1,903

README

Metric API

PkgGoDev

Documentation

Overview

Package metric provides the OpenTelemetry API used to measure metrics about source code operation.

This API is separate from its implementation so the instrumentation built from it is reusable. See go.opentelemetry.io/otel/sdk/metric for the official OpenTelemetry implementation of this API.

All measurements made with this package are made via instruments. These instruments are created by a Meter which itself is created by a MeterProvider. Applications need to accept a MeterProvider implementation as a starting point when instrumenting. This can be done directly, or by using the OpenTelemetry global MeterProvider via GetMeterProvider. Using an appropriately named Meter from the accepted MeterProvider, instrumentation can then be built from the Meter's instruments.

Instruments

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, and 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, and 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, and Float64ObservableCounter) are designed to measure values that never decrease in value, but instead only incrementally increase in value. UpDownCounters (Int64UpDownCounter, Float64UpDownCounter, Int64ObservableUpDownCounter, and 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 and Float64Histogram) should be used. Finally, when just the most recent measurement needs to be conveyed about an asynchronous measurement, a Gauge (Int64ObservableGauge and Float64ObservableGauge) should be used.

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

Instrument Name

OpenTelemetry defines an instrument name syntax that restricts what instrument names are allowed.

Instrument names should ...

  • Not be empty.
  • Have an alphabetic character as their first letter.
  • Have any letter after the first be an alphanumeric character, ‘_’, ‘.’, ‘-’, or ‘/’.
  • Have a maximum length of 255 letters.

To ensure compatibility with observability platforms, all instruments created need to conform to this syntax. Not all implementations of the API will validate these names, it is the callers responsibility to ensure compliance.

Measurements

Measurements are made by recording values and information about the values with an instrument. How these measurements are recorded depends on the instrument.

Measurements for synchronous instruments (Int64Counter, Int64UpDownCounter, Int64Histogram, Float64Counter, Float64UpDownCounter, and Float64Histogram) are recorded using the instrument methods directly. All counter instruments have an Add method that is used to measure an increment value, and all histogram instruments have a Record method to measure a data point.

Asynchronous instruments (Int64ObservableCounter, Int64ObservableUpDownCounter, Int64ObservableGauge, Float64ObservableCounter, Float64ObservableUpDownCounter, and Float64ObservableGauge) record measurements within a callback function. The callback is registered with the Meter which ensures the callback is called once per collection cycle. A callback can be registered two ways: during the instrument's creation using an option, or later using the RegisterCallback method of the Meter that created the instrument.

If the following criteria are met, an option (WithInt64Callback or WithFloat64Callback) can be used during the asynchronous instrument's creation to register a callback (Int64Callback or Float64Callback, respectively):

  • The measurement process is known when the instrument is created
  • Only that instrument will make a measurement within the callback
  • The callback never needs to be unregistered

If the criteria are not met, use the RegisterCallback method of the Meter that created the instrument to register a Callback.

API Implementations

This package does not conform to the standard Go versioning policy, all of its interfaces may have methods added to them without a package major version bump. This non-standard API evolution could surprise an uninformed implementation author. They could unknowingly build their implementation in a way that would result in a runtime panic for their users that update to the new API.

The API is designed to help inform an instrumentation author about this non-standard API evolution. It requires them to choose a default behavior for unimplemented interface methods. There are three behavior choices they can make:

  • Compilation failure
  • Panic
  • Default to another implementation

All interfaces in this API embed a corresponding interface from go.opentelemetry.io/otel/metric/embedded. If an author wants the default behavior of their implementations to be a compilation failure, signaling to their users they need to update to the latest version of that implementation, they need to embed the corresponding interface from go.opentelemetry.io/otel/metric/embedded in their implementation. For example, 

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

type MeterProvider struct {
	embedded.MeterProvider
	// ...
}

If an author wants the default behavior of their implementations to a panic, they need to embed the API interface directly. 

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

type MeterProvider struct {
	metric.MeterProvider
	// ...
}

This is not a recommended behavior as it could lead to publishing packages that contain runtime panics when users update other package that use newer versions of go.opentelemetry.io/otel/metric.

Finally, an author can embed another implementation in theirs. The embedded implementation will be used for methods not defined by the author. For example, an author who wants to default to silently dropping the call can use go.opentelemetry.io/otel/metric/noop: 

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

type MeterProvider struct {
	noop.MeterProvider
	// ...
}

It is strongly recommended that authors only embed go.opentelemetry.io/otel/metric/noop if they choose this default behavior. That implementation is the only one OpenTelemetry authors can guarantee will fully implement all the API interfaces when a user updates their API.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AddConfig added in v0.38.0 

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

AddConfig contains options for an addition measurement.

func NewAddConfig added in v0.38.0 

func NewAddConfig(opts []AddOption) AddConfig

NewAddConfig returns a new AddConfig with all opts applied.

func (AddConfig) Attributes added in v0.38.0 

func (c AddConfig) Attributes() attribute.Set

Attributes returns the configured attribute set.

type AddOption added in v0.38.0 

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

AddOption applies options to an addition measurement. See MeasurementOption for other options that can be used as an AddOption.

type Callback added in v0.35.0 

type Callback func(context.Context, Observer) error

Callback is a function registered with a Meter that makes observations for the set of instruments it is registered with. The Observer parameter is used to record measurement observations for these instruments.

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 Callbacks. Meaning, it should not report measurements for an instrument with the same attributes as another Callback will report.

The function needs to be concurrent safe.

type Float64Callback added in v0.38.0 

type Float64Callback func(context.Context, Float64Observer) error

Float64Callback is a function registered with a Meter that makes observations for a Float64Observable 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 

type Float64Counter interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Float64Counter

	// Add records a change to the counter.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Add(ctx context.Context, incr float64, options ...AddOption)
}

Float64Counter is an instrument that records increasing float64 values.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Float64CounterConfig added in v0.38.0 

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

Float64CounterConfig contains options for synchronous counter instruments that record float64 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 added in v0.38.0 

func (c Float64CounterConfig) Description() string

Description returns the configured description.

func (Float64CounterConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as a Float64CounterOption.

type Float64Gauge added in v1.27.0 

type Float64Gauge interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Float64Gauge

	// Record records the instantaneous value.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Record(ctx context.Context, value float64, options ...RecordOption)
}

Float64Gauge is an instrument that records instantaneous float64 values.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Float64GaugeConfig added in v1.27.0 

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

Float64GaugeConfig contains options for synchronous gauge instruments that record float64 values.

func NewFloat64GaugeConfig added in v1.27.0 

func NewFloat64GaugeConfig(opts ...Float64GaugeOption) Float64GaugeConfig

NewFloat64GaugeConfig returns a new Float64GaugeConfig with all opts applied.

func (Float64GaugeConfig) Description added in v1.27.0 

func (c Float64GaugeConfig) Description() string

Description returns the configured description.

func (Float64GaugeConfig) Unit added in v1.27.0 

func (c Float64GaugeConfig) Unit() string

Unit returns the configured unit.

type Float64GaugeOption added in v1.27.0 

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

Float64GaugeOption applies options to a Float64GaugeConfig. See InstrumentOption for other options that can be used as a Float64GaugeOption.

type Float64Histogram added in v0.23.0 

type Float64Histogram interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Float64Histogram

	// Record adds an additional value to the distribution.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Record(ctx context.Context, incr float64, options ...RecordOption)
}

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

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Float64HistogramConfig added in v0.38.0 

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

Float64HistogramConfig contains options for synchronous histogram instruments that record float64 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 added in v0.38.0 

func (c Float64HistogramConfig) Description() string

Description returns the configured description.

func (Float64HistogramConfig) ExplicitBucketBoundaries added in v1.20.0 

func (c Float64HistogramConfig) ExplicitBucketBoundaries() []float64

ExplicitBucketBoundaries returns the configured explicit bucket boundaries.

func (Float64HistogramConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as a Float64HistogramOption.

type Float64Observable added in v0.38.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.38.0 

type Float64ObservableCounter interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Float64ObservableCounter

	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. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Float64ObservableCounterConfig added in v0.38.0 

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

Float64ObservableCounterConfig contains options for asynchronous counter instruments that record float64 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 added in v0.38.0 

func (c Float64ObservableCounterConfig) Callbacks() []Float64Callback

Callbacks returns the configured callbacks.

func (Float64ObservableCounterConfig) Description added in v0.38.0 

func (c Float64ObservableCounterConfig) Description() string

Description returns the configured description.

func (Float64ObservableCounterConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as a Float64ObservableCounterOption.

type Float64ObservableGauge added in v0.38.0 

type Float64ObservableGauge interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Float64ObservableGauge

	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. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Float64ObservableGaugeConfig added in v0.38.0 

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

Float64ObservableGaugeConfig contains options for asynchronous counter instruments that record float64 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 added in v0.38.0 

func (c Float64ObservableGaugeConfig) Callbacks() []Float64Callback

Callbacks returns the configured callbacks.

func (Float64ObservableGaugeConfig) Description added in v0.38.0 

func (c Float64ObservableGaugeConfig) Description() string

Description returns the configured description.

func (Float64ObservableGaugeConfig) Unit added in v0.38.0 

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 InstrumentOption 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.38.0 

func WithFloat64Callback(callback Float64Callback) Float64ObservableOption

WithFloat64Callback adds callback to be called for an instrument.

type Float64ObservableUpDownCounter added in v0.38.0 

type Float64ObservableUpDownCounter interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Float64ObservableUpDownCounter

	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. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Float64ObservableUpDownCounterConfig added in v0.38.0 

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

Float64ObservableUpDownCounterConfig contains options for asynchronous counter instruments that record float64 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 added in v0.38.0 

func (c Float64ObservableUpDownCounterConfig) Callbacks() []Float64Callback

Callbacks returns the configured callbacks.

func (Float64ObservableUpDownCounterConfig) Description added in v0.38.0 

func (c Float64ObservableUpDownCounterConfig) Description() string

Description returns the configured description.

func (Float64ObservableUpDownCounterConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as a Float64ObservableUpDownCounterOption.

type Float64Observer added in v0.38.0 

type Float64Observer interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Float64Observer

	// Observe records the float64 value.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Observe(value float64, options ...ObserveOption)
}

Float64Observer is a recorder of float64 measurements.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Float64UpDownCounter 

type Float64UpDownCounter interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Float64UpDownCounter

	// Add records a change to the counter.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Add(ctx context.Context, incr float64, options ...AddOption)
}

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

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Float64UpDownCounterConfig added in v0.38.0 

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

Float64UpDownCounterConfig contains options for synchronous counter instruments that record float64 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 added in v0.38.0 

func (c Float64UpDownCounterConfig) Description() string

Description returns the configured description.

func (Float64UpDownCounterConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as a Float64UpDownCounterOption.

type HistogramOption added in v1.20.0 

type HistogramOption interface {
	Int64HistogramOption
	Float64HistogramOption
}

HistogramOption applies options to histogram instruments.

func WithExplicitBucketBoundaries added in v1.20.0 

func WithExplicitBucketBoundaries(bounds ...float64) HistogramOption

WithExplicitBucketBoundaries sets the instrument explicit bucket boundaries.

This option is considered "advisory", and may be ignored by API implementations.

type InstrumentOption 

type InstrumentOption interface {
	Int64CounterOption
	Int64UpDownCounterOption
	Int64HistogramOption
	Int64GaugeOption
	Int64ObservableCounterOption
	Int64ObservableUpDownCounterOption
	Int64ObservableGaugeOption

	Float64CounterOption
	Float64UpDownCounterOption
	Float64HistogramOption
	Float64GaugeOption
	Float64ObservableCounterOption
	Float64ObservableUpDownCounterOption
	Float64ObservableGaugeOption
}

InstrumentOption applies options to all instruments.

func WithDescription 

func WithDescription(desc string) InstrumentOption

WithDescription sets the instrument description.

func WithUnit 

func WithUnit(u string) InstrumentOption

WithUnit sets the instrument unit.

The unit u should be defined using the appropriate [UCUM](https://ucum.org) case-sensitive code.

type Int64Callback added in v0.38.0 

type Int64Callback func(context.Context, Int64Observer) error

Int64Callback is a function registered with a Meter that makes observations for an Int64Observable 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 

type Int64Counter interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Int64Counter

	// Add records a change to the counter.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Add(ctx context.Context, incr int64, options ...AddOption)
}

Int64Counter is an instrument that records increasing int64 values.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

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 added in v0.38.0 

func (c Int64CounterConfig) Description() string

Description returns the configured description.

func (Int64CounterConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as an Int64CounterOption.

type Int64Gauge added in v1.27.0 

type Int64Gauge interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Int64Gauge

	// Record records the instantaneous value.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Record(ctx context.Context, value int64, options ...RecordOption)
}

Int64Gauge is an instrument that records instantaneous int64 values.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Int64GaugeConfig added in v1.27.0 

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

Int64GaugeConfig contains options for synchronous gauge instruments that record int64 values.

func NewInt64GaugeConfig added in v1.27.0 

func NewInt64GaugeConfig(opts ...Int64GaugeOption) Int64GaugeConfig

NewInt64GaugeConfig returns a new Int64GaugeConfig with all opts applied.

func (Int64GaugeConfig) Description added in v1.27.0 

func (c Int64GaugeConfig) Description() string

Description returns the configured description.

func (Int64GaugeConfig) Unit added in v1.27.0 

func (c Int64GaugeConfig) Unit() string

Unit returns the configured unit.

type Int64GaugeOption added in v1.27.0 

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

Int64GaugeOption applies options to a Int64GaugeConfig. See InstrumentOption for other options that can be used as a Int64GaugeOption.

type Int64Histogram added in v0.23.0 

type Int64Histogram interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Int64Histogram

	// Record adds an additional value to the distribution.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Record(ctx context.Context, incr int64, options ...RecordOption)
}

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

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Int64HistogramConfig added in v0.38.0 

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

Int64HistogramConfig contains options for synchronous histogram 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 added in v0.38.0 

func (c Int64HistogramConfig) Description() string

Description returns the configured description.

func (Int64HistogramConfig) ExplicitBucketBoundaries added in v1.20.0 

func (c Int64HistogramConfig) ExplicitBucketBoundaries() []float64

ExplicitBucketBoundaries returns the configured explicit bucket boundaries.

func (Int64HistogramConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as an Int64HistogramOption.

type Int64Observable added in v0.38.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.38.0 

type Int64ObservableCounter interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Int64ObservableCounter

	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. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

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 added in v0.38.0 

func (c Int64ObservableCounterConfig) Callbacks() []Int64Callback

Callbacks returns the configured callbacks.

func (Int64ObservableCounterConfig) Description added in v0.38.0 

func (c Int64ObservableCounterConfig) Description() string

Description returns the configured description.

func (Int64ObservableCounterConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as an Int64ObservableCounterOption.

type Int64ObservableGauge added in v0.38.0 

type Int64ObservableGauge interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Int64ObservableGauge

	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. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

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 added in v0.38.0 

func (c Int64ObservableGaugeConfig) Callbacks() []Int64Callback

Callbacks returns the configured callbacks.

func (Int64ObservableGaugeConfig) Description added in v0.38.0 

func (c Int64ObservableGaugeConfig) Description() string

Description returns the configured description.

func (Int64ObservableGaugeConfig) Unit added in v0.38.0 

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 InstrumentOption 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.38.0 

func WithInt64Callback(callback Int64Callback) Int64ObservableOption

WithInt64Callback adds callback to be called for an instrument.

type Int64ObservableUpDownCounter added in v0.38.0 

type Int64ObservableUpDownCounter interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Int64ObservableUpDownCounter

	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. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

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 added in v0.38.0 

func (c Int64ObservableUpDownCounterConfig) Callbacks() []Int64Callback

Callbacks returns the configured callbacks.

func (Int64ObservableUpDownCounterConfig) Description added in v0.38.0 

func (c Int64ObservableUpDownCounterConfig) Description() string

Description returns the configured description.

func (Int64ObservableUpDownCounterConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as an Int64ObservableUpDownCounterOption.

type Int64Observer added in v0.38.0 

type Int64Observer interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Int64Observer

	// Observe records the int64 value.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Observe(value int64, options ...ObserveOption)
}

Int64Observer is a recorder of int64 measurements.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type Int64UpDownCounter 

type Int64UpDownCounter interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Int64UpDownCounter

	// Add records a change to the counter.
	//
	// Use the WithAttributeSet (or, if performance is not a concern,
	// the WithAttributes) option to include measurement attributes.
	Add(ctx context.Context, incr int64, options ...AddOption)
}

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

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

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 added in v0.38.0 

func (c Int64UpDownCounterConfig) Description() string

Description returns the configured description.

func (Int64UpDownCounterConfig) Unit added in v0.38.0 

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 InstrumentOption for other options that can be used as an Int64UpDownCounterOption.

type MeasurementOption added in v0.38.0 

type MeasurementOption interface {
	AddOption
	RecordOption
	ObserveOption
}

MeasurementOption applies options to all instrument measurement.

func WithAttributeSet added in v0.38.0 

func WithAttributeSet(attributes attribute.Set) MeasurementOption

WithAttributeSet sets the attribute Set associated with a measurement is made with.

If multiple WithAttributeSet or WithAttributes options are passed the attributes will be merged together in the order they are passed. Attributes with duplicate keys will use the last value passed.

func WithAttributes added in v0.38.0 

func WithAttributes(attributes ...attribute.KeyValue) MeasurementOption

WithAttributes converts attributes into an attribute Set and sets the Set to be associated with a measurement. This is shorthand for: 

cp := make([]attribute.KeyValue, len(attributes))
copy(cp, attributes)
WithAttributeSet(attribute.NewSet(cp...))

attribute.NewSet may modify the passed attributes so this will make a copy of attributes before creating a set in order to ensure this function is concurrent safe. This makes this option function less optimized in comparison to WithAttributeSet. Therefore, WithAttributeSet should be preferred for performance sensitive code.

See WithAttributeSet for information about how multiple WithAttributes are merged.

type Meter 

type Meter interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Meter

	// Int64Counter returns a new Int64Counter instrument identified by name
	// and configured with options. The instrument is used to synchronously
	// record increasing int64 measurements during a computational operation.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Int64Counter(name string, options ...Int64CounterOption) (Int64Counter, error)

	// Int64UpDownCounter returns a new Int64UpDownCounter instrument
	// identified by name and configured with options. The instrument is used
	// to synchronously record int64 measurements during a computational
	// operation.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error)

	// Int64Histogram returns a new Int64Histogram instrument identified by
	// name and configured with options. The instrument is used to
	// synchronously record the distribution of int64 measurements during a
	// computational operation.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Int64Histogram(name string, options ...Int64HistogramOption) (Int64Histogram, error)

	// Int64Gauge returns a new Int64Gauge instrument identified by name and
	// configured with options. The instrument is used to synchronously record
	// instantaneous int64 measurements during a computational operation.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Int64Gauge(name string, options ...Int64GaugeOption) (Int64Gauge, error)

	// Int64ObservableCounter returns a new Int64ObservableCounter identified
	// by name and configured with options. The instrument is used to
	// asynchronously record increasing int64 measurements once per a
	// measurement collection cycle.
	//
	// Measurements for the returned instrument are made via a callback. Use
	// the WithInt64Callback option to register the callback here, or use the
	// RegisterCallback method of this Meter to register one later. See the
	// Measurements section of the package documentation for more information.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Int64ObservableCounter(name string, options ...Int64ObservableCounterOption) (Int64ObservableCounter, error)

	// Int64ObservableUpDownCounter returns a new Int64ObservableUpDownCounter
	// instrument identified by name and configured with options. The
	// instrument is used to asynchronously record int64 measurements once per
	// a measurement collection cycle.
	//
	// Measurements for the returned instrument are made via a callback. Use
	// the WithInt64Callback option to register the callback here, or use the
	// RegisterCallback method of this Meter to register one later. See the
	// Measurements section of the package documentation for more information.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Int64ObservableUpDownCounter(name string, options ...Int64ObservableUpDownCounterOption) (Int64ObservableUpDownCounter, error)

	// Int64ObservableGauge returns a new Int64ObservableGauge instrument
	// identified by name and configured with options. The instrument is used
	// to asynchronously record instantaneous int64 measurements once per a
	// measurement collection cycle.
	//
	// Measurements for the returned instrument are made via a callback. Use
	// the WithInt64Callback option to register the callback here, or use the
	// RegisterCallback method of this Meter to register one later. See the
	// Measurements section of the package documentation for more information.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Int64ObservableGauge(name string, options ...Int64ObservableGaugeOption) (Int64ObservableGauge, error)

	// Float64Counter returns a new Float64Counter instrument identified by
	// name and configured with options. The instrument is used to
	// synchronously record increasing float64 measurements during a
	// computational operation.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Float64Counter(name string, options ...Float64CounterOption) (Float64Counter, error)

	// Float64UpDownCounter returns a new Float64UpDownCounter instrument
	// identified by name and configured with options. The instrument is used
	// to synchronously record float64 measurements during a computational
	// operation.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error)

	// Float64Histogram returns a new Float64Histogram instrument identified by
	// name and configured with options. The instrument is used to
	// synchronously record the distribution of float64 measurements during a
	// computational operation.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Float64Histogram(name string, options ...Float64HistogramOption) (Float64Histogram, error)

	// Float64Gauge returns a new Float64Gauge instrument identified by name and
	// configured with options. The instrument is used to synchronously record
	// instantaneous float64 measurements during a computational operation.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Float64Gauge(name string, options ...Float64GaugeOption) (Float64Gauge, error)

	// Float64ObservableCounter returns a new Float64ObservableCounter
	// instrument identified by name and configured with options. The
	// instrument is used to asynchronously record increasing float64
	// measurements once per a measurement collection cycle.
	//
	// Measurements for the returned instrument are made via a callback. Use
	// the WithFloat64Callback option to register the callback here, or use the
	// RegisterCallback method of this Meter to register one later. See the
	// Measurements section of the package documentation for more information.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Float64ObservableCounter(name string, options ...Float64ObservableCounterOption) (Float64ObservableCounter, error)

	// Float64ObservableUpDownCounter returns a new
	// Float64ObservableUpDownCounter instrument identified by name and
	// configured with options. The instrument is used to asynchronously record
	// float64 measurements once per a measurement collection cycle.
	//
	// Measurements for the returned instrument are made via a callback. Use
	// the WithFloat64Callback option to register the callback here, or use the
	// RegisterCallback method of this Meter to register one later. See the
	// Measurements section of the package documentation for more information.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Float64ObservableUpDownCounter(name string, options ...Float64ObservableUpDownCounterOption) (Float64ObservableUpDownCounter, error)

	// Float64ObservableGauge returns a new Float64ObservableGauge instrument
	// identified by name and configured with options. The instrument is used
	// to asynchronously record instantaneous float64 measurements once per a
	// measurement collection cycle.
	//
	// Measurements for the returned instrument are made via a callback. Use
	// the WithFloat64Callback option to register the callback here, or use the
	// RegisterCallback method of this Meter to register one later. See the
	// Measurements section of the package documentation for more information.
	//
	// The name needs to conform to the OpenTelemetry instrument name syntax.
	// See the Instrument Name section of the package documentation for more
	// information.
	Float64ObservableGauge(name string, options ...Float64ObservableGaugeOption) (Float64ObservableGauge, error)

	// RegisterCallback registers f to be called during the collection of a
	// measurement cycle.
	//
	// If Unregister of the returned Registration is called, f needs to be
	// unregistered and not called during collection.
	//
	// The instruments f is registered with are the only instruments that f may
	// observe values for.
	//
	// If no instruments are passed, f should not be registered nor called
	// during collection.
	//
	// The function f needs to be concurrent safe.
	RegisterCallback(f Callback, instruments ...Observable) (Registration, error)
}

Meter provides access to instrument instances for recording metrics.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

Example (Asynchronous_multiple) 
package main

import (
	"context"
	"fmt"
	"runtime"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/metric"
)

var meter = otel.Meter("my-service-meter")

func main() {
	// This is just a sample of memory stats to record from the Memstats
	heapAlloc, err := meter.Int64ObservableUpDownCounter("heapAllocs")
	if err != nil {
		fmt.Println("failed to register updown counter for heapAllocs")
		panic(err)
	}
	gcCount, err := meter.Int64ObservableCounter("gcCount")
	if err != nil {
		fmt.Println("failed to register counter for gcCount")
		panic(err)
	}

	_, err = meter.RegisterCallback(
		func(_ context.Context, o metric.Observer) error {
			memStats := &runtime.MemStats{}
			// This call does work
			runtime.ReadMemStats(memStats)

			o.ObserveInt64(heapAlloc, int64(memStats.HeapAlloc))
			o.ObserveInt64(gcCount, int64(memStats.NumGC))

			return nil
		},
		heapAlloc,
		gcCount,
	)
	if err != nil {
		fmt.Println("Failed to register callback")
		panic(err)
	}
}

Output:
Example (Asynchronous_single) 
package main

import (
	"context"
	"fmt"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/metric"
)

var meter = otel.Meter("my-service-meter")

func main() {
	_, err := meter.Int64ObservableGauge(
		"DiskUsage",
		metric.WithUnit("By"),
		metric.WithInt64Callback(func(_ context.Context, obsrv metric.Int64Observer) error {
			// Do the real work here to get the real disk usage. For example,
			//
			//   usage, err := GetDiskUsage(diskID)
			//   if err != nil {
			//   	if retryable(err) {
			//   		// Retry the usage measurement.
			//   	} else {
			//   		return err
			//   	}
			//   }
			//
			// For demonstration purpose, a static value is used here.
			usage := 75000
			obsrv.Observe(int64(usage), metric.WithAttributes(attribute.Int("disk.id", 3)))
			return nil
		}),
	)
	if err != nil {
		fmt.Println("failed to register instrument")
		panic(err)
	}
}

Output:
Example (Attributes)

You can add Attributes by using the WithAttributeSet and WithAttributes options.

Here's how you might add the HTTP status code attribute to your recordings. 

package main

import (
	"net/http"

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

	semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)

var meter = otel.Meter("my-service-meter")

func main() {
	apiCounter, err := meter.Int64UpDownCounter(
		"api.finished.counter",
		metric.WithDescription("Number of finished API calls."),
		metric.WithUnit("{call}"),
	)
	if err != nil {
		panic(err)
	}
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		// do some work in an API call and set the response HTTP status code
		statusCode := http.StatusOK

		apiCounter.Add(r.Context(), 1,
			metric.WithAttributes(semconv.HTTPResponseStatusCode(statusCode)))
	})
}

Output:
Example (Counter)

Counters can be used to measure a non-negative, increasing value.

Here's how you might report the number of calls for an HTTP handler. 

package main

import (
	"net/http"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/metric"
)

var meter = otel.Meter("my-service-meter")

func main() {
	apiCounter, err := meter.Int64Counter(
		"api.counter",
		metric.WithDescription("Number of API calls."),
		metric.WithUnit("{call}"),
	)
	if err != nil {
		panic(err)
	}
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		apiCounter.Add(r.Context(), 1)

		// do some work in an API call
	})
}

Output:
Example (Gauge)

Gauges can be used to record non-additive values when changes occur.

Here's how you might report the current speed of a cpu fan. 

package main

import (
	"context"
	"math/rand"
	"time"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/metric"
)

var meter = otel.Meter("my-service-meter")

func main() {
	speedGauge, err := meter.Int64Gauge(
		"cpu.fan.speed",
		metric.WithDescription("Speed of CPU fan"),
		metric.WithUnit("RPM"),
	)
	if err != nil {
		panic(err)
	}

	getCPUFanSpeed := func() int64 {
		// Generates a random fan speed for demonstration purpose.
		// In real world applications, replace this to get the actual fan speed.
		return int64(1500 + rand.Intn(1000))
	}

	fanSpeedSubscription := make(chan int64, 1)
	go func() {
		defer close(fanSpeedSubscription)

		for idx := 0; idx < 5; idx++ {
			// Synchronous gauges are used when the measurement cycle is
			// synchronous to an external change.
			// Simulate that external cycle here.
			time.Sleep(time.Duration(rand.Intn(3)) * time.Second)
			fanSpeed := getCPUFanSpeed()
			fanSpeedSubscription <- fanSpeed
		}
	}()

	ctx := context.Background()
	for fanSpeed := range fanSpeedSubscription {
		speedGauge.Record(ctx, fanSpeed)
	}
}

Output:
Example (Histogram)

Histograms are used to measure a distribution of values over time.

Here's how you might report a distribution of response times for an HTTP handler. 

package main

import (
	"net/http"
	"time"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/metric"
)

var meter = otel.Meter("my-service-meter")

func main() {
	histogram, err := meter.Float64Histogram(
		"task.duration",
		metric.WithDescription("The duration of task execution."),
		metric.WithUnit("s"),
		metric.WithExplicitBucketBoundaries(.005, .01, .025, .05, .075, .1, .25, .5, .75, 1, 2.5, 5, 7.5, 10),
	)
	if err != nil {
		panic(err)
	}
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()

		// do some work in an API call

		duration := time.Since(start)
		histogram.Record(r.Context(), duration.Seconds())
	})
}

Output:
Example (ObservableCounter)

Observable counters can be used to measure an additive, non-negative, monotonically increasing value.

Here's how you might report time since the application started. 

package main

import (
	"context"
	"time"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/metric"
)

var meter = otel.Meter("my-service-meter")

func main() {
	start := time.Now()
	if _, err := meter.Float64ObservableCounter(
		"uptime",
		metric.WithDescription("The duration since the application started."),
		metric.WithUnit("s"),
		metric.WithFloat64Callback(func(_ context.Context, o metric.Float64Observer) error {
			o.Observe(float64(time.Since(start).Seconds()))
			return nil
		}),
	); err != nil {
		panic(err)
	}
}

Output:
Example (ObservableGauge)

Observable Gauges should be used to measure non-additive values.

Here's how you might report memory usage of the heap objects used in application. 

package main

import (
	"context"
	"runtime"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/metric"
)

var meter = otel.Meter("my-service-meter")

func main() {
	if _, err := meter.Int64ObservableGauge(
		"memory.heap",
		metric.WithDescription(
			"Memory usage of the allocated heap objects.",
		),
		metric.WithUnit("By"),
		metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
			var m runtime.MemStats
			runtime.ReadMemStats(&m)
			o.Observe(int64(m.HeapAlloc))
			return nil
		}),
	); err != nil {
		panic(err)
	}
}

Output:
Example (ObservableUpDownCounter)

Observable UpDown counters can increment and decrement, allowing you to measure an additive, non-negative, non-monotonically increasing cumulative value.

Here's how you might report some database metrics. 

package main

import (
	"context"
	"database/sql"

	"go.opentelemetry.io/otel/metric"
)

func main() {
	// The function registers asynchronous metrics for the provided db.
	// Make sure to unregister metric.Registration before closing the provided db.
	_ = func(db *sql.DB, meter metric.Meter, poolName string) (metric.Registration, error) {
		m, err := meter.Int64ObservableUpDownCounter(
			"db.client.connections.max",
			metric.WithDescription("The maximum number of open connections allowed."),
			metric.WithUnit("{connection}"),
		)
		if err != nil {
			return nil, err
		}

		waitTime, err := meter.Int64ObservableUpDownCounter(
			"db.client.connections.wait_time",
			metric.WithDescription("The time it took to obtain an open connection from the pool."),
			metric.WithUnit("ms"),
		)
		if err != nil {
			return nil, err
		}

		reg, err := meter.RegisterCallback(
			func(_ context.Context, o metric.Observer) error {
				stats := db.Stats()
				o.ObserveInt64(m, int64(stats.MaxOpenConnections))
				o.ObserveInt64(waitTime, int64(stats.WaitDuration))
				return nil
			},
			m,
			waitTime,
		)
		if err != nil {
			return nil, err
		}
		return reg, nil
	}
}

Output:
Example (Synchronous) 
package main

import (
	"context"
	"fmt"
	"time"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/metric"
)

var meter = otel.Meter("my-service-meter")

func main() {
	// Create a histogram using the global MeterProvider.
	workDuration, err := meter.Int64Histogram(
		"workDuration",
		metric.WithUnit("ms"))
	if err != nil {
		fmt.Println("Failed to register instrument")
		panic(err)
	}

	startTime := time.Now()
	ctx := context.Background()
	// Do work
	// ...
	workDuration.Record(ctx, time.Since(startTime).Milliseconds())
}

Output:
Example (UpDownCounter)

UpDown counters can increment and decrement, allowing you to observe a cumulative value that goes up or down.

Here's how you might report the number of items of some collection. 

package main

import (
	"context"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/metric"
)

var meter = otel.Meter("my-service-meter")

func main() {
	var err error
	itemsCounter, err := meter.Int64UpDownCounter(
		"items.counter",
		metric.WithDescription("Number of items."),
		metric.WithUnit("{item}"),
	)
	if err != nil {
		panic(err)
	}

	_ = func() {
		// code that adds an item to the collection
		itemsCounter.Add(context.Background(), 1)
	}

	_ = func() {
		// code that removes an item from the collection
		itemsCounter.Add(context.Background(), -1)
	}
}

Output:

type MeterConfig 

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

MeterConfig contains options for Meters.

func NewMeterConfig 

func NewMeterConfig(opts ...MeterOption) MeterConfig

NewMeterConfig creates a new MeterConfig and applies all the given options.

func (MeterConfig) InstrumentationAttributes added in v0.37.0 

func (cfg MeterConfig) InstrumentationAttributes() attribute.Set

InstrumentationAttributes returns the attributes associated with the library providing instrumentation.

func (MeterConfig) InstrumentationVersion 

func (cfg MeterConfig) InstrumentationVersion() string

InstrumentationVersion returns the version of the library providing instrumentation.

func (MeterConfig) SchemaURL added in v0.24.0 

func (cfg MeterConfig) SchemaURL() string

SchemaURL is the schema_url of the library providing instrumentation.

type MeterOption 

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

MeterOption is an interface for applying Meter options.

func WithInstrumentationAttributes added in v0.37.0 

func WithInstrumentationAttributes(attr ...attribute.KeyValue) MeterOption

WithInstrumentationAttributes sets the instrumentation attributes.

The passed attributes will be de-duplicated.

func WithInstrumentationVersion 

func WithInstrumentationVersion(version string) MeterOption

WithInstrumentationVersion sets the instrumentation version.

func WithSchemaURL added in v0.24.0 

func WithSchemaURL(schemaURL string) MeterOption

WithSchemaURL sets the schema URL.

type MeterProvider 

type MeterProvider interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.MeterProvider

	// Meter returns a new Meter with the provided name and configuration.
	//
	// A Meter should be scoped at most to a single package. The name needs to
	// be unique so it does not collide with other names used by
	// an application, nor other applications. To achieve this, the import path
	// of the instrumentation package is recommended to be used as name.
	//
	// If the name is empty, then an implementation defined default name will
	// be used instead.
	Meter(name string, opts ...MeterOption) Meter
}

MeterProvider provides access to named Meter instances, for instrumenting an application or package.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

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 ObserveConfig added in v0.38.0 

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

ObserveConfig contains options for an observed measurement.

func NewObserveConfig added in v0.38.0 

func NewObserveConfig(opts []ObserveOption) ObserveConfig

NewObserveConfig returns a new ObserveConfig with all opts applied.

func (ObserveConfig) Attributes added in v0.38.0 

func (c ObserveConfig) Attributes() attribute.Set

Attributes returns the configured attribute set.

type ObserveOption added in v0.38.0 

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

ObserveOption applies options to an addition measurement. See MeasurementOption for other options that can be used as a ObserveOption.

type Observer added in v0.35.0 

type Observer interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Observer

	// ObserveFloat64 records the float64 value for obsrv.
	ObserveFloat64(obsrv Float64Observable, value float64, opts ...ObserveOption)

	// ObserveInt64 records the int64 value for obsrv.
	ObserveInt64(obsrv Int64Observable, value int64, opts ...ObserveOption)
}

Observer records measurements for multiple instruments in a Callback.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

type RecordConfig added in v0.38.0 

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

RecordConfig contains options for a recorded measurement.

func NewRecordConfig added in v0.38.0 

func NewRecordConfig(opts []RecordOption) RecordConfig

NewRecordConfig returns a new RecordConfig with all opts applied.

func (RecordConfig) Attributes added in v0.38.0 

func (c RecordConfig) Attributes() attribute.Set

Attributes returns the configured attribute set.

type RecordOption added in v0.38.0 

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

RecordOption applies options to an addition measurement. See MeasurementOption for other options that can be used as a RecordOption.

type Registration added in v0.35.0 

type Registration interface {
	// Users of the interface can ignore this. This embedded type is only used
	// by implementations of this interface. See the "API Implementations"
	// section of the package documentation for more information.
	embedded.Registration

	// Unregister removes the callback registration from a Meter.
	//
	// This method needs to be idempotent and concurrent safe.
	Unregister() error
}

Registration is an token representing the unique registration of a callback for a set of instruments with a Meter.

Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.

Source Files

View all Source files

Directories

Path Synopsis
Package embedded provides interfaces embedded within the [OpenTelemetry metric API].
 Package embedded provides interfaces embedded within the [OpenTelemetry metric API].
Package noop provides an implementation of the OpenTelemetry metric API that produces no telemetry and minimizes used computation resources.
 Package noop provides an implementation of the OpenTelemetry metric API that produces no telemetry and minimizes used computation resources.

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.