metric

Documentation

Overview

Package metric implements the OpenTelemetry `Meter` API. The SDK supports configurable metrics export behavior through a `export.MetricBatcher` API. Most metrics behavior is controlled by the `MetricBatcher`, including:

1. Selecting the concrete type of aggregation to use 2. Receiving exported data during SDK.Collect()

The call to SDK.Collect() initiates collection. The SDK calls the `MetricBatcher` for each current record, asking the aggregator to export itself. Aggregators, found in `./aggregators`, are responsible for receiving updates and exporting their current state.

The SDK.Collect() API should be called by an exporter. During the call to Collect(), the exporter receives calls in a single-threaded context. No locking is required because the SDK.Collect() call prevents concurrency.

The SDK uses lock-free algorithms to maintain its internal state. There are three central data structures at work:

1. A sync.Map maps unique (InstrumentID, LabelSet) to records 2. A "primary" atomic list of records 3. A "reclaim" atomic list of records

Collection is oriented around epochs. The SDK internally has a notion of the "current" epoch, which is incremented each time Collect() is called. Records contain two atomic counter values, the epoch in which it was last modified and the epoch in which it was last collected. Records may be garbage collected when the epoch in which they were last updated is less than the epoch in which they were last collected.

Collect() performs a record-by-record scan of all active records and exports their current state, before incrementing the current epoch. Collection events happen at a point in time during `Collect()`, but all records are not collected in the same instant.

The purpose of the two lists: the primary list is appended-to when new handles are created and atomically cleared during collect. The reclaim list is used as a second chance, in case there is a race between looking up a record and record deletion.

Index

• type SDK
  • func New(exporter export.MetricBatcher) *SDK
  • func (m *SDK) Collect(ctx context.Context)
  • func (m *SDK) GetDescriptor(inst metric.InstrumentImpl) *export.Descriptor
  • func (m *SDK) Labels(kvs ...core.KeyValue) api.LabelSet
  • func (m *SDK) NewFloat64Counter(name string, cos ...api.CounterOptionApplier) api.Float64Counter
  • func (m *SDK) NewFloat64Gauge(name string, gos ...api.GaugeOptionApplier) api.Float64Gauge
  • func (m *SDK) NewFloat64Measure(name string, mos ...api.MeasureOptionApplier) api.Float64Measure
  • func (m *SDK) NewInt64Counter(name string, cos ...api.CounterOptionApplier) api.Int64Counter
  • func (m *SDK) NewInt64Gauge(name string, gos ...api.GaugeOptionApplier) api.Int64Gauge
  • func (m *SDK) NewInt64Measure(name string, mos ...api.MeasureOptionApplier) api.Int64Measure
  • func (m *SDK) RecordBatch(ctx context.Context, ls api.LabelSet, measurements ...api.Measurement)

Types

type SDK

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

SDK implements the OpenTelemetry Meter API. The SDK is bound to a single export.MetricBatcher in `New()`.

The SDK supports a Collect() API to gather and export current data. Collect() should be arranged according to the exporter model. Push-based exporters will setup a timer to call Collect() periodically. Pull-based exporters will call Collect() when a pull request arrives.

func New

func New(exporter export.MetricBatcher) *SDK

New constructs a new SDK for the given exporter. This SDK supports only a single exporter.

The SDK does not start any background process to collect itself periodically, this responsbility lies with the exporter, typically, depending on the type of export. For example, a pull-based exporter will call Collect() when it receives a request to scrape current metric values. A push-based exporter should configure its own periodic collection.

func (*SDK) Collect

func (m *SDK) Collect(ctx context.Context)

Collect traverses the list of active records and exports data for each active instrument. Collect() may not be called concurrently.

During the collection pass, the export.MetricBatcher will receive one Export() call per current aggregation.

func (*SDK) GetDescriptor

func (m *SDK) GetDescriptor(inst metric.InstrumentImpl) *export.Descriptor

GetDescriptor returns the descriptor of an instrument, which is not part of the public metric API.

func (*SDK) Labels

func (m *SDK) Labels(kvs ...core.KeyValue) api.LabelSet

Labels returns a LabelSet corresponding to the arguments. Passed labels are de-duplicated, with last-value-wins semantics.

func (*SDK) NewFloat64Counter

func (m *SDK) NewFloat64Counter(name string, cos ...api.CounterOptionApplier) api.Float64Counter

func (*SDK) NewFloat64Gauge

func (m *SDK) NewFloat64Gauge(name string, gos ...api.GaugeOptionApplier) api.Float64Gauge

func (*SDK) NewFloat64Measure

func (m *SDK) NewFloat64Measure(name string, mos ...api.MeasureOptionApplier) api.Float64Measure

func (*SDK) NewInt64Counter

func (m *SDK) NewInt64Counter(name string, cos ...api.CounterOptionApplier) api.Int64Counter

func (*SDK) NewInt64Gauge

func (m *SDK) NewInt64Gauge(name string, gos ...api.GaugeOptionApplier) api.Int64Gauge

func (*SDK) NewInt64Measure

func (m *SDK) NewInt64Measure(name string, mos ...api.MeasureOptionApplier) api.Int64Measure

func (*SDK) RecordBatch

func (m *SDK) RecordBatch(ctx context.Context, ls api.LabelSet, measurements ...api.Measurement)

RecordBatch enters a batch of metric events.