metric package - go.opentelemetry.io/otel/metric - Go Packages (original) (raw)
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 aMeterProvider. 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, Int64Gauge, Float64Counter, Float64UpDownCounter,Float64Histogram, and Float64Gauge) 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, andFloat64ObservableGauge) 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, andFloat64ObservableUpDownCounter) 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, a Gauge (Int64Gauge, Float64Gauge, Int64ObservableGauge, andFloat64ObservableGauge) should be used: the synchronous variants record an instantaneous value at a specific point in code, while the observable variants sample the value via a callback once per collection cycle.
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, Int64Gauge, Float64Counter, Float64UpDownCounter,Float64Histogram, and Float64Gauge) 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 and synchronous gauge instruments have a Record method to measure a data point.
Asynchronous instruments (Int64ObservableCounter,Int64ObservableUpDownCounter, Int64ObservableGauge,Float64ObservableCounter, Float64ObservableUpDownCounter, andFloat64ObservableGauge) 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 orWithFloat64Callback) 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.
Avoiding Expensive Computations ¶
All synchronous instruments provide an Enabled method that reports whether the instrument will process measurements for the given context. When no SDK is registered or the instrument is otherwise disabled, Enabled returns false. This can be used to avoid expensive measurement work when a measurement will not be recorded:
if counter.Enabled(ctx) { counter.Add(ctx, 1, metric.WithAttributes(expensiveAttributes()...)) }
This is especially valuable when computing attributes is expensive.WithAttributes performs non-trivial work on every call to build anattribute.Set from the provided attributes, and that work is wasted if the measurement is not recorded.
For performance sensitive code where the same attribute set is used repeatedly, prefer WithAttributeSet. It accepts a pre-built attribute.Set, letting you pay the construction cost once and reuse it across many measurements:
attrs := attribute.NewSet(attribute.String("key", "val")) // ... later, on each call: counter.Add(ctx, 1, metric.WithAttributeSet(attrs))
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 fromgo.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 fromgo.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 usego.opentelemetry.io/otel/metric/noop:
import "go.opentelemetry.io/otel/metric/noop"
type MeterProvider struct { noop.MeterProvider // ... }
It is strongly recommended that authors only embedgo.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.
This section is empty.
This section is empty.
This section is empty.
type AddConfig struct {
}
AddConfig contains options for an addition measurement.
func NewAddConfig(opts []AddOption) AddConfig
NewAddConfig returns a new AddConfig with all opts applied.
Attributes returns the configured attribute set.
type AddOption interface {
}
AddOption applies options to an addition measurement. SeeMeasurementOption for other options that can be used as an AddOption.
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 reentrant and concurrent safe.
Note that Go's mutexes are not reentrant, and locking a mutex takes an indefinite amount of time. It is therefore advised to avoid using mutexes inside callbacks.
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 reentrant and concurrent safe.
Note that Go's mutexes are not reentrant, and locking a mutex takes an indefinite amount of time. It is therefore advised to avoid using mutexes inside callbacks.
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 struct {
}
Float64CounterConfig contains options for synchronous counter instruments that record float64 values.
func NewFloat64CounterConfig(opts ...Float64CounterOption) Float64CounterConfig
NewFloat64CounterConfig returns a new Float64CounterConfig with all opts applied.
Description returns the configured description.
Unit returns the configured unit.
type Float64CounterOption interface {
}
Float64CounterOption applies options to a Float64CounterConfig. SeeInstrumentOption for other options that can be used as a Float64CounterOption.
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 struct {
}
Float64GaugeConfig contains options for synchronous gauge instruments that record float64 values.
func NewFloat64GaugeConfig(opts ...Float64GaugeOption) Float64GaugeConfig
NewFloat64GaugeConfig returns a new Float64GaugeConfig with all opts applied.
Description returns the configured description.
Unit returns the configured unit.
type Float64GaugeOption interface {
}
Float64GaugeOption applies options to a Float64GaugeConfig. SeeInstrumentOption for other options that can be used as a Float64GaugeOption.
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 struct {
}
Float64HistogramConfig contains options for synchronous histogram instruments that record float64 values.
func NewFloat64HistogramConfig(opts ...Float64HistogramOption) Float64HistogramConfig
NewFloat64HistogramConfig returns a new Float64HistogramConfig with all opts applied.
Description returns the configured description.
func (c Float64HistogramConfig) ExplicitBucketBoundaries() []float64
ExplicitBucketBoundaries returns the configured explicit bucket boundaries.
Unit returns the configured unit.
type Float64HistogramOption interface {
}
Float64HistogramOption applies options to a Float64HistogramConfig. SeeInstrumentOption for other options that can be used as a Float64HistogramOption.
type Float64Observable interface { Observable
}
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.
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 struct {
}
Float64ObservableCounterConfig contains options for asynchronous counter instruments that record float64 values.
func NewFloat64ObservableCounterConfig(opts ...Float64ObservableCounterOption) Float64ObservableCounterConfig
NewFloat64ObservableCounterConfig returns a newFloat64ObservableCounterConfig with all opts applied.
func (c Float64ObservableCounterConfig) Callbacks() []Float64Callback
Callbacks returns the configured callbacks.
Description returns the configured description.
Unit returns the configured unit.
type Float64ObservableCounterOption interface {
}
Float64ObservableCounterOption applies options to aFloat64ObservableCounterConfig. See Float64ObservableOption andInstrumentOption for other options that can be used as a Float64ObservableCounterOption.
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 struct {
}
Float64ObservableGaugeConfig contains options for asynchronous counter instruments that record float64 values.
func NewFloat64ObservableGaugeConfig(opts ...Float64ObservableGaugeOption) Float64ObservableGaugeConfig
NewFloat64ObservableGaugeConfig returns a new Float64ObservableGaugeConfigwith all opts applied.
func (c Float64ObservableGaugeConfig) Callbacks() []Float64Callback
Callbacks returns the configured callbacks.
Description returns the configured description.
Unit returns the configured unit.
type Float64ObservableGaugeOption interface {
}
Float64ObservableGaugeOption applies options to aFloat64ObservableGaugeConfig. See Float64ObservableOption andInstrumentOption for other options that can be used as a Float64ObservableGaugeOption.
Float64ObservableOption applies options to float64 Observer instruments.
func WithFloat64Callback(callback Float64Callback) Float64ObservableOption
WithFloat64Callback adds callback to be called for an instrument.
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 struct {
}
Float64ObservableUpDownCounterConfig contains options for asynchronous counter instruments that record float64 values.
func NewFloat64ObservableUpDownCounterConfig( opts ...Float64ObservableUpDownCounterOption, ) Float64ObservableUpDownCounterConfig
NewFloat64ObservableUpDownCounterConfig returns a newFloat64ObservableUpDownCounterConfig with all opts applied.
Callbacks returns the configured callbacks.
Description returns the configured description.
Unit returns the configured unit.
type Float64ObservableUpDownCounterOption interface {
}
Float64ObservableUpDownCounterOption applies options to aFloat64ObservableUpDownCounterConfig. See Float64ObservableOption andInstrumentOption for other options that can be used as a Float64ObservableUpDownCounterOption.
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.
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 struct {
}
Float64UpDownCounterConfig contains options for synchronous counter instruments that record float64 values.
func NewFloat64UpDownCounterConfig(opts ...Float64UpDownCounterOption) Float64UpDownCounterConfig
NewFloat64UpDownCounterConfig returns a new Float64UpDownCounterConfigwith all opts applied.
Description returns the configured description.
Unit returns the configured unit.
type Float64UpDownCounterOption interface {
}
Float64UpDownCounterOption applies options to aFloat64UpDownCounterConfig. See InstrumentOption for other options that can be used as a Float64UpDownCounterOption.
type HistogramOption interface { Int64HistogramOption Float64HistogramOption }
HistogramOption applies options to histogram instruments.
func WithExplicitBucketBoundaries(bounds ...float64) HistogramOption
WithExplicitBucketBoundaries sets the instrument explicit bucket boundaries.
This option is considered "advisory", and may be ignored by API implementations.
InstrumentOption applies options to all instruments.
WithDescription sets the instrument description.
WithUnit sets the instrument unit.
The unit u should be defined using the appropriate [UCUM](https://ucum.org) case-sensitive code.
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 reentrant and concurrent safe.
Note that Go's mutexes are not reentrant, and locking a mutex takes an indefinite amount of time. It is therefore advised to avoid using mutexes inside callbacks.
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 struct {
}
Int64CounterConfig contains options for synchronous counter instruments that record int64 values.
func NewInt64CounterConfig(opts ...Int64CounterOption) Int64CounterConfig
NewInt64CounterConfig returns a new Int64CounterConfig with all opts applied.
Description returns the configured description.
Unit returns the configured unit.
type Int64CounterOption interface {
}
Int64CounterOption applies options to a Int64CounterConfig. SeeInstrumentOption for other options that can be used as an Int64CounterOption.
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 struct {
}
Int64GaugeConfig contains options for synchronous gauge instruments that record int64 values.
func NewInt64GaugeConfig(opts ...Int64GaugeOption) Int64GaugeConfig
NewInt64GaugeConfig returns a new Int64GaugeConfig with all opts applied.
Description returns the configured description.
Unit returns the configured unit.
type Int64GaugeOption interface {
}
Int64GaugeOption applies options to a Int64GaugeConfig. SeeInstrumentOption for other options that can be used as a Int64GaugeOption.
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 struct {
}
Int64HistogramConfig contains options for synchronous histogram instruments that record int64 values.
func NewInt64HistogramConfig(opts ...Int64HistogramOption) Int64HistogramConfig
NewInt64HistogramConfig returns a new Int64HistogramConfig with all opts applied.
Description returns the configured description.
func (c Int64HistogramConfig) ExplicitBucketBoundaries() []float64
ExplicitBucketBoundaries returns the configured explicit bucket boundaries.
Unit returns the configured unit.
type Int64HistogramOption interface {
}
Int64HistogramOption applies options to a Int64HistogramConfig. SeeInstrumentOption for other options that can be used as an Int64HistogramOption.
type Int64Observable interface { Observable
}
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.
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 struct {
}
Int64ObservableCounterConfig contains options for asynchronous counter instruments that record int64 values.
func NewInt64ObservableCounterConfig(opts ...Int64ObservableCounterOption) Int64ObservableCounterConfig
NewInt64ObservableCounterConfig returns a new Int64ObservableCounterConfigwith all opts applied.
func (c Int64ObservableCounterConfig) Callbacks() []Int64Callback
Callbacks returns the configured callbacks.
Description returns the configured description.
Unit returns the configured unit.
type Int64ObservableCounterOption interface {
}
Int64ObservableCounterOption applies options to aInt64ObservableCounterConfig. See Int64ObservableOption andInstrumentOption for other options that can be used as an Int64ObservableCounterOption.
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 struct {
}
Int64ObservableGaugeConfig contains options for asynchronous counter instruments that record int64 values.
func NewInt64ObservableGaugeConfig(opts ...Int64ObservableGaugeOption) Int64ObservableGaugeConfig
NewInt64ObservableGaugeConfig returns a new Int64ObservableGaugeConfigwith all opts applied.
func (c Int64ObservableGaugeConfig) Callbacks() []Int64Callback
Callbacks returns the configured callbacks.
Description returns the configured description.
Unit returns the configured unit.
type Int64ObservableGaugeOption interface {
}
Int64ObservableGaugeOption applies options to aInt64ObservableGaugeConfig. See Int64ObservableOption andInstrumentOption for other options that can be used as an Int64ObservableGaugeOption.
Int64ObservableOption applies options to int64 Observer instruments.
func WithInt64Callback(callback Int64Callback) Int64ObservableOption
WithInt64Callback adds callback to be called for an instrument.
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 struct {
}
Int64ObservableUpDownCounterConfig contains options for asynchronous counter instruments that record int64 values.
func NewInt64ObservableUpDownCounterConfig( opts ...Int64ObservableUpDownCounterOption, ) Int64ObservableUpDownCounterConfig
NewInt64ObservableUpDownCounterConfig returns a newInt64ObservableUpDownCounterConfig with all opts applied.
func (c Int64ObservableUpDownCounterConfig) Callbacks() []Int64Callback
Callbacks returns the configured callbacks.
Description returns the configured description.
Unit returns the configured unit.
type Int64ObservableUpDownCounterOption interface {
}
Int64ObservableUpDownCounterOption applies options to aInt64ObservableUpDownCounterConfig. See Int64ObservableOption andInstrumentOption for other options that can be used as an Int64ObservableUpDownCounterOption.
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.
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 struct {
}
Int64UpDownCounterConfig contains options for synchronous counter instruments that record int64 values.
func NewInt64UpDownCounterConfig(opts ...Int64UpDownCounterOption) Int64UpDownCounterConfig
NewInt64UpDownCounterConfig returns a new Int64UpDownCounterConfig with all opts applied.
Description returns the configured description.
Unit returns the configured unit.
type Int64UpDownCounterOption interface {
}
Int64UpDownCounterOption applies options to a Int64UpDownCounterConfig. See InstrumentOption for other options that can be used as an Int64UpDownCounterOption.
type MeasurementOption interface { AddOption RecordOption ObserveOption }
MeasurementOption applies options to all instrument measurement.
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.
Experimental: The returned option may implementgo.opentelemetry.io/otel/metric/x.Settableattribute.Set, which can be used to replace the option's attribute set and reuse the option without additional allocations. This behavior is experimental and may be changed or removed in a future release without notice.
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.
Experimental: The returned option may implementgo.opentelemetry.io/otel/metric/x.Settable[[]attribute.KeyValue], which can be used to replace the option's attributes and reuse the option without additional allocations. This behavior is experimental and may be changed or removed in a future release without notice.
type Meter interface {
[embedded](/go.opentelemetry.io/otel/metric@v1.44.0/embedded).[Meter](/go.opentelemetry.io/otel/metric@v1.44.0/embedded#Meter)
Int64Counter(name [string](/builtin#string), options ...[Int64CounterOption](#Int64CounterOption)) ([Int64Counter](#Int64Counter), [error](/builtin#error))
Int64UpDownCounter(name [string](/builtin#string), options ...[Int64UpDownCounterOption](#Int64UpDownCounterOption)) ([Int64UpDownCounter](#Int64UpDownCounter), [error](/builtin#error))
Int64Histogram(name [string](/builtin#string), options ...[Int64HistogramOption](#Int64HistogramOption)) ([Int64Histogram](#Int64Histogram), [error](/builtin#error))
Int64Gauge(name [string](/builtin#string), options ...[Int64GaugeOption](#Int64GaugeOption)) ([Int64Gauge](#Int64Gauge), [error](/builtin#error))
Int64ObservableCounter(name [string](/builtin#string), options ...[Int64ObservableCounterOption](#Int64ObservableCounterOption)) ([Int64ObservableCounter](#Int64ObservableCounter), [error](/builtin#error))
Int64ObservableUpDownCounter(
name [string](/builtin#string),
options ...[Int64ObservableUpDownCounterOption](#Int64ObservableUpDownCounterOption),
) ([Int64ObservableUpDownCounter](#Int64ObservableUpDownCounter), [error](/builtin#error))
Int64ObservableGauge(name [string](/builtin#string), options ...[Int64ObservableGaugeOption](#Int64ObservableGaugeOption)) ([Int64ObservableGauge](#Int64ObservableGauge), [error](/builtin#error))
Float64Counter(name [string](/builtin#string), options ...[Float64CounterOption](#Float64CounterOption)) ([Float64Counter](#Float64Counter), [error](/builtin#error))
Float64UpDownCounter(name [string](/builtin#string), options ...[Float64UpDownCounterOption](#Float64UpDownCounterOption)) ([Float64UpDownCounter](#Float64UpDownCounter), [error](/builtin#error))
Float64Histogram(name [string](/builtin#string), options ...[Float64HistogramOption](#Float64HistogramOption)) ([Float64Histogram](#Float64Histogram), [error](/builtin#error))
Float64Gauge(name [string](/builtin#string), options ...[Float64GaugeOption](#Float64GaugeOption)) ([Float64Gauge](#Float64Gauge), [error](/builtin#error))
Float64ObservableCounter(name [string](/builtin#string), options ...[Float64ObservableCounterOption](#Float64ObservableCounterOption)) ([Float64ObservableCounter](#Float64ObservableCounter), [error](/builtin#error))
Float64ObservableUpDownCounter(
name [string](/builtin#string),
options ...[Float64ObservableUpDownCounterOption](#Float64ObservableUpDownCounterOption),
) ([Float64ObservableUpDownCounter](#Float64ObservableUpDownCounter), [error](/builtin#error))
Float64ObservableGauge(name [string](/builtin#string), options ...[Float64ObservableGaugeOption](#Float64ObservableGaugeOption)) ([Float64ObservableGauge](#Float64ObservableGauge), [error](/builtin#error))
RegisterCallback(f [Callback](#Callback), instruments ...[Observable](#Observable)) ([Registration](#Registration), [error](/builtin#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.
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)
}}
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) } }
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.41.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(_ 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)))
})}
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(_ http.ResponseWriter, r *http.Request) { apiCounter.Add(r.Context(), 1)
// do some work in an API call
})}
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.
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 range 5 {
// 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) }
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(_ 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())
})}
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) } }
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) } }
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"
"go.opentelemetry.io/otel/metric")
var meter = otel.Meter("my-service-meter")
func main() { m, err := meter.Int64ObservableUpDownCounter( "db.client.connections.max", metric.WithDescription("The maximum number of open connections allowed."), metric.WithUnit("{connection}"), ) if err != nil { panic(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 {
panic(err)
}
var db *sql.DB // DB is initialized elsewhere.
_, 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 {
panic(err)
}}
Use [Int64Counter.Enabled] to avoid performing expensive operations when the instrument is not being observed. Use WithAttributeSet to pre-build anattribute.Set once and reuse it across many measurements.
package main
import ( "net/http"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"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) }
// Pre-build the attribute set once at init time.
attrs := metric.WithAttributeSet(attribute.NewSet(
attribute.String("api.name", "users"),
))
http.HandleFunc("/", func(_ http.ResponseWriter, r *http.Request) {
// Enabled returns false when no SDK is registered or when a view
// drops this instrument, avoiding all measurement overhead.
if apiCounter.Enabled(r.Context()) {
apiCounter.Add(r.Context(), 1, attrs)
}
})}
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())}
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) }
// Add an item to the collection.
itemsCounter.Add(context.Background(), 1)
// Remove an item from the collection.
itemsCounter.Add(context.Background(), -1)}
type MeterConfig struct {
}
MeterConfig contains options for Meters.
func NewMeterConfig(opts ...MeterOption) MeterConfig
NewMeterConfig creates a new MeterConfig and applies all the given options.
InstrumentationAttributes returns the attributes associated with the library providing instrumentation.
func (cfg MeterConfig) InstrumentationVersion() string
InstrumentationVersion returns the version of the library providing instrumentation.
SchemaURL is the schema_url of the library providing instrumentation.
type MeterOption interface {
}
MeterOption is an interface for applying Meter options.
WithInstrumentationAttributeSet adds the instrumentation attributes.
If multiple WithInstrumentationAttributes or WithInstrumentationAttributeSetoptions are passed, the attributes will be merged together in the order they are passed. Attributes with duplicate keys will use the last value passed.
WithInstrumentationAttributes adds the instrumentation attributes.
This is equivalent to calling WithInstrumentationAttributeSet with anattribute.Set created from a clone of the passed attributes.WithInstrumentationAttributeSet is recommended for more control.
If multiple WithInstrumentationAttributes or WithInstrumentationAttributeSetoptions 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 WithInstrumentationVersion(version string) MeterOption
WithInstrumentationVersion sets the instrumentation version.
func WithSchemaURL(schemaURL string) MeterOption
WithSchemaURL sets the schema URL.
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 interface {
}
Observable is used as a grouping mechanism for all instruments that are updated within a Callback.
type ObserveConfig struct {
}
ObserveConfig contains options for an observed measurement.
func NewObserveConfig(opts []ObserveOption) ObserveConfig
NewObserveConfig returns a new ObserveConfig with all opts applied.
Attributes returns the configured attribute set.
type ObserveOption interface {
}
ObserveOption applies options to an addition measurement. SeeMeasurementOption for other options that can be used as a 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 struct {
}
RecordConfig contains options for a recorded measurement.
func NewRecordConfig(opts []RecordOption) RecordConfig
NewRecordConfig returns a new RecordConfig with all opts applied.
Attributes returns the configured attribute set.
type RecordOption interface {
}
RecordOption applies options to an addition measurement. SeeMeasurementOption for other options that can be used as a RecordOption.
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.