metric

Documentation

Overview

Package metric provides an implementation of the OpenTelemetry metric SDK.

See https://opentelemetry.io/docs/concepts/signals/metrics/ for information about the concept of OpenTelemetry metrics and https://opentelemetry.io/docs/concepts/components/ for more information about OpenTelemetry SDKs.

The entry point for the metric package is the MeterProvider. It is the object that all API calls use to create Meters, instruments, and ultimately make metric measurements. Also, it is an object that should be used to control the life-cycle (start, flush, and shutdown) of the SDK.

A MeterProvider needs to be configured to export the measured data, this is done by configuring it with a Reader implementation (using the WithReader MeterProviderOption). Readers take two forms: ones that push to an endpoint (NewPeriodicReader), and ones that an endpoint pulls from. See the go.opentelemetry.io/otel/exporters package for exporters that can be used as or with these Readers.

Each Reader, when registered with the MeterProvider, can be augmented with a View. Views allow users that run OpenTelemetry instrumented code to modify the generated data of that instrumentation. See the go.opentelemetry.io/otel/sdk/metric/view package for more information about Views.

The data generated by a MeterProvider needs to include information about its origin. A MeterProvider needs to be configured with a Resource, using the WithResource MeterProviderOption, to include this information. This Resource should be used to describe the unique runtime environment instrumented code is being run on. That way when multiple instances of the code are collected at a single endpoint their origin is decipherable.

Example

package main

import (
	"context"
	"log"

	"go.opentelemetry.io/otel/metric/global"
	"go.opentelemetry.io/otel/sdk/metric"
	"go.opentelemetry.io/otel/sdk/resource"

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

func main() {
	// This reader is used as a stand-in for a reader that will actually export
	// data. See exporters in the go.opentelemetry.io/otel/exporters package
	// for more information.
	reader := metric.NewManualReader()

	// See the go.opentelemetry.io/otel/sdk/resource package for more
	// information about how to create and use Resources.
	res := resource.NewWithAttributes(
		semconv.SchemaURL,
		semconv.ServiceNameKey.String("my-service"),
		semconv.ServiceVersionKey.String("v0.1.0"),
	)

	meterProvider := metric.NewMeterProvider(
		metric.WithResource(res),
		metric.WithReader(reader),
	)
	global.SetMeterProvider(meterProvider)
	defer func() {
		err := meterProvider.Shutdown(context.Background())
		if err != nil {
			log.Fatalln(err)
		}
	}()
	// The MeterProvider is configured and registered globally. You can now run
	// your code instrumented with the OpenTelemetry API that uses the global
	// MeterProvider without having to pass this MeterProvider instance. Or,
	// you can pass this instance directly to your instrumented code if it
	// accepts a MeterProvider instance.
	//
	// See the go.opentelemetry.io/otel/metric package for more information
	// about the metric API.
}

Index

• Variables
• func DefaultAggregationSelector(ik view.InstrumentKind) aggregation.Aggregation
• func DefaultTemporalitySelector(view.InstrumentKind) metricdata.Temporality
• type AggregationSelector
• type Exporter
• type ManualReaderOption
• type MeterProvider
  • func NewMeterProvider(options ...Option) *MeterProvider
  • func (mp *MeterProvider) ForceFlush(ctx context.Context) error
  • func (mp *MeterProvider) Meter(name string, options ...metric.MeterOption) metric.Meter
  • func (mp *MeterProvider) Shutdown(ctx context.Context) error
• type Option
  • func WithReader(r Reader, views ...view.View) Option
  • func WithResource(res *resource.Resource) Option
• type PeriodicReaderOption
  • func WithInterval(d time.Duration) PeriodicReaderOption
  • func WithTimeout(d time.Duration) PeriodicReaderOption
• type Reader
  • func NewManualReader(opts ...ManualReaderOption) Reader
  • func NewPeriodicReader(exporter Exporter, options ...PeriodicReaderOption) Reader
• type ReaderOption
  • func WithAggregationSelector(selector AggregationSelector) ReaderOption
  • func WithTemporalitySelector(selector TemporalitySelector) ReaderOption
• type TemporalitySelector

Examples

• Package

Variables

var ErrExporterShutdown = fmt.Errorf("exporter is shutdown")

ErrExporterShutdown is returned if Export or Shutdown are called after an Exporter has been Shutdown.

var ErrReaderNotRegistered = fmt.Errorf("reader is not registered")

ErrReaderNotRegistered is returned if Collect or Shutdown are called before the reader is registered with a MeterProvider.

var ErrReaderShutdown = fmt.Errorf("reader is shutdown")

ErrReaderShutdown is returned if Collect or Shutdown are called after a reader has been Shutdown once.

Functions

func DefaultAggregationSelector

func DefaultAggregationSelector(ik view.InstrumentKind) aggregation.Aggregation

DefaultAggregationSelector returns the default aggregation and parameters that will be used to summarize measurement made from an instrument of InstrumentKind. This AggregationSelector using the following selection mapping: Counter ⇨ Sum, Asynchronous Counter ⇨ Sum, UpDownCounter ⇨ Sum, Asynchronous UpDownCounter ⇨ Sum, Asynchronous Gauge ⇨ LastValue, Histogram ⇨ ExplicitBucketHistogram.

func DefaultTemporalitySelector

func DefaultTemporalitySelector(view.InstrumentKind) metricdata.Temporality

DefaultTemporalitySelector is the default TemporalitySelector used if WithTemporalitySelector is not provided. CumulativeTemporality will be used for all instrument kinds if this TemporalitySelector is used.

Types

type AggregationSelector

type AggregationSelector func(view.InstrumentKind) aggregation.Aggregation

AggregationSelector selects the aggregation and the parameters to use for that aggregation based on the InstrumentKind.

type Exporter

type Exporter interface {
	// Export serializes and transmits metric data to a receiver.
	//
	// This is called synchronously, there is no concurrency safety
	// requirement. Because of this, it is critical that all timeouts and
	// cancellations of the passed context be honored.
	//
	// All retry logic must be contained in this function. The SDK does not
	// implement any retry logic. All errors returned by this function are
	// considered unrecoverable and will be reported to a configured error
	// Handler.
	Export(context.Context, metricdata.ResourceMetrics) error

	// ForceFlush flushes any metric data held by an exporter.
	//
	// The deadline or cancellation of the passed context must be honored. An
	// appropriate error should be returned in these situations.
	ForceFlush(context.Context) error

	// Shutdown flushes all metric data held by an exporter and releases any
	// held computational resources.
	//
	// The deadline or cancellation of the passed context must be honored. An
	// appropriate error should be returned in these situations.
	//
	// After Shutdown is called, calls to Export will perform no operation and
	// instead will return an error indicating the shutdown state.
	Shutdown(context.Context) error
}

Exporter handles the delivery of metric data to external receivers. This is the final component in the metric push pipeline.

type ManualReaderOption

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

ManualReaderOption applies a configuration option value to a ManualReader.

type MeterProvider

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

MeterProvider handles the creation and coordination of Meters. All Meters created by a MeterProvider will be associated with the same Resource, have the same Views applied to them, and have their produced metric telemetry passed to the configured Readers.

func NewMeterProvider

func NewMeterProvider(options ...Option) *MeterProvider

NewMeterProvider returns a new and configured MeterProvider.

By default, the returned MeterProvider is configured with the default Resource and no Readers. Readers cannot be added after a MeterProvider is created. This means the returned MeterProvider, one created with no Readers, will perform no operations.

func (*MeterProvider) ForceFlush

func (mp *MeterProvider) ForceFlush(ctx context.Context) error

ForceFlush flushes all pending telemetry.

This method honors the deadline or cancellation of ctx. An appropriate error will be returned in these situations. There is no guaranteed that all telemetry be flushed or all resources have been released in these situations.

This method is safe to call concurrently.

func (*MeterProvider) Meter

func (mp *MeterProvider) Meter(name string, options ...metric.MeterOption) metric.Meter

Meter returns a Meter with the given name and configured with options.

The name should be the name of the instrumentation scope creating telemetry. This name may be the same as the instrumented code only if that code provides built-in instrumentation.

If name is empty, the default (go.opentelemetry.io/otel/sdk/meter) will be used.

Calls to the Meter method after Shutdown has been called will return Meters that perform no operations.

This method is safe to call concurrently.

func (*MeterProvider) Shutdown

func (mp *MeterProvider) Shutdown(ctx context.Context) error

Shutdown shuts down the MeterProvider flushing all pending telemetry and releasing any held computational resources.

This call is idempotent. The first call will perform all flush and releasing operations. Subsequent calls will perform no action and will return an error stating this.

Measurements made by instruments from meters this MeterProvider created will not be exported after Shutdown is called.

This method honors the deadline or cancellation of ctx. An appropriate error will be returned in these situations. There is no guaranteed that all telemetry be flushed or all resources have been released in these situations.

This method is safe to call concurrently.

type Option

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

Option applies a configuration option value to a MeterProvider.

func WithReader

func WithReader(r Reader, views ...view.View) Option

WithReader associates a Reader with a MeterProvider. Any passed view config will be used to associate a view with the Reader. If no views are passed the default view will be use for the Reader.

Passing this option multiple times for the same Reader will overwrite. The last option passed will be the one used for that Reader.

By default, if this option is not used, the MeterProvider will perform no operations; no data will be exported without a Reader.

func WithResource

func WithResource(res *resource.Resource) Option

WithResource associates a Resource with a MeterProvider. This Resource represents the entity producing telemetry and is associated with all Meters the MeterProvider will create.

By default, if this Option is not used, the default Resource from the go.opentelemetry.io/otel/sdk/resource package will be used.

type PeriodicReaderOption

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

PeriodicReaderOption applies a configuration option value to a PeriodicReader.

func WithInterval

func WithInterval(d time.Duration) PeriodicReaderOption

WithInterval configures the intervening time between exports for a PeriodicReader.

If this option is not used or d is less than or equal to zero, 60 seconds is used as the default.

func WithTimeout

func WithTimeout(d time.Duration) PeriodicReaderOption

WithTimeout configures the time a PeriodicReader waits for an export to complete before canceling it.

If this option is not used or d is less than or equal to zero, 30 seconds is used as the default.

type Reader

type Reader interface {

	// Collect gathers and returns all metric data related to the Reader from
	// the SDK. An error is returned if this is called after Shutdown.
	Collect(context.Context) (metricdata.ResourceMetrics, error)

	// ForceFlush flushes all metric measurements held in an export pipeline.
	//
	// This deadline or cancellation of the passed context are honored. An appropriate
	// error will be returned in these situations. There is no guaranteed that all
	// telemetry be flushed or all resources have been released in these
	// situations.
	ForceFlush(context.Context) error

	// Shutdown flushes all metric measurements held in an export pipeline and releases any
	// held computational resources.
	//
	// This deadline or cancellation of the passed context are honored. An appropriate
	// error will be returned in these situations. There is no guaranteed that all
	// telemetry be flushed or all resources have been released in these
	// situations.
	//
	// After Shutdown is called, calls to Collect will perform no operation and instead will return
	// an error indicating the shutdown state.
	Shutdown(context.Context) error
	// contains filtered or unexported methods
}

Reader is the interface used between the SDK and an exporter. Control flow is bi-directional through the Reader, since the SDK initiates ForceFlush and Shutdown while the initiates collection. The Register() method here informs the Reader that it can begin reading, signaling the start of bi-directional control flow.

Typically, push-based exporters that are periodic will implement PeroidicExporter themselves and construct a PeriodicReader to satisfy this interface.

Pull-based exporters will typically implement Register themselves, since they read on demand.

func NewManualReader

func NewManualReader(opts ...ManualReaderOption) Reader

NewManualReader returns a Reader which is directly called to collect metrics.

func NewPeriodicReader

func NewPeriodicReader(exporter Exporter, options ...PeriodicReaderOption) Reader

NewPeriodicReader returns a Reader that collects and exports metric data to the exporter at a defined interval. By default, the returned Reader will collect and export data every 60 seconds, and will cancel export attempts that exceed 30 seconds. The export time is not counted towards the interval between attempts.

The Collect method of the returned Reader continues to gather and return metric data to the user. It will not automatically send that data to the exporter. That is left to the user to accomplish.

type ReaderOption

type ReaderOption interface {
	ManualReaderOption
	PeriodicReaderOption
}

ReaderOption applies a configuration option value to either a ManualReader or a PeriodicReader.

func WithAggregationSelector

func WithAggregationSelector(selector AggregationSelector) ReaderOption

WithAggregationSelector sets the AggregationSelector a reader will use to determine the aggregation to use for an instrument based on its kind. If this option is not used, the reader will use the DefaultAggregationSelector or the aggregation explicitly passed for a view matching an instrument.

func WithTemporalitySelector

func WithTemporalitySelector(selector TemporalitySelector) ReaderOption

WithTemporalitySelector sets the TemporalitySelector a reader will use to determine the Temporality of an instrument based on its kind. If this option is not used, the reader will use the DefaultTemporalitySelector.

type TemporalitySelector

type TemporalitySelector func(view.InstrumentKind) metricdata.Temporality

TemporalitySelector selects the temporality to use based on the InstrumentKind.