package metric

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

Index ¶

• func IteratorToSlice(iter LabelIterator) []core.KeyValue
• type AggregationSelector
• type Aggregator
• type Batcher
• type CheckpointSet
• type Exporter
• type LabelEncoder
• type LabelIterator
• func NewLabelIterator(storage LabelStorage) LabelIterator
• func (i *LabelIterator) IndexedLabel() (int, core.KeyValue)
• func (i *LabelIterator) Label() core.KeyValue
• func (i *LabelIterator) Len() int
• func (i *LabelIterator) Next() bool
• type LabelSlice
• func (s LabelSlice) GetLabel(idx int) core.KeyValue
• func (s LabelSlice) Iter() LabelIterator
• func (s LabelSlice) NumLabels() int
• type LabelStorage
• type Labels
• func NewLabels(storage LabelStorage, encoded string, encoder LabelEncoder) Labels
• func (l Labels) Encoded() string
• func (l Labels) Encoder() LabelEncoder
• func (l Labels) Iter() LabelIterator
• type Record
• func NewRecord(descriptor *metric.Descriptor, labels Labels, aggregator Aggregator) Record
• func (r Record) Aggregator() Aggregator
• func (r Record) Descriptor() *metric.Descriptor
• func (r Record) Labels() Labels

Functions ¶

func IteratorToSlice ¶

func IteratorToSlice(iter LabelIterator) []core.KeyValue

Convenience function that creates a slice of labels from the passed iterator. The iterator is set up to start from the beginning before creating the slice.

Types ¶

type AggregationSelector ¶

type AggregationSelector interface {
	// AggregatorFor returns the kind of aggregator suited to the
	// requested export.  Returning `nil` indicates to ignore this
	// metric instrument.  This must return a consistent type to
	// avoid confusion in later stages of the metrics export
	// process, i.e., when Merging multiple aggregators for a
	// specific instrument.
	//
	// Note: This is context-free because the aggregator should
	// not relate to the incoming context.  This call should not
	// block.
	AggregatorFor(*metric.Descriptor) Aggregator
}

AggregationSelector supports selecting the kind of Aggregator to use at runtime for a specific metric instrument.

type Aggregator ¶

type Aggregator interface {
	// Update receives a new measured value and incorporates it
	// into the aggregation.  Update() calls may arrive
	// concurrently as the SDK does not provide synchronization.
	//
	// Descriptor.NumberKind() should be consulted to determine
	// whether the provided number is an int64 or float64.
	//
	// The Context argument comes from user-level code and could be
	// inspected for distributed or span context.
	Update(context.Context, core.Number, *metric.Descriptor) error

	// Checkpoint is called during collection to finish one period
	// of aggregation by atomically saving the current value.
	// Checkpoint() is called concurrently with Update().
	// Checkpoint should reset the current state to the empty
	// state, in order to begin computing a new delta for the next
	// collection period.
	//
	// After the checkpoint is taken, the current value may be
	// accessed using by converting to one a suitable interface
	// types in the `aggregator` sub-package.
	//
	// The Context argument originates from the controller that
	// orchestrates collection.
	Checkpoint(context.Context, *metric.Descriptor)

	// Merge combines the checkpointed state from the argument
	// aggregator into this aggregator's checkpointed state.
	// Merge() is called in a single-threaded context, no locking
	// is required.
	Merge(Aggregator, *metric.Descriptor) error
}

Aggregator implements a specific aggregation behavior, e.g., a behavior to track a sequence of updates to a counter, a measure, or an observer instrument. For the most part, counter semantics are fixed and the provided implementation should be used. Measure and observer metrics offer a wide range of potential tradeoffs and several implementations are provided.

Aggregators are meant to compute the change (i.e., delta) in state from one checkpoint to the next, with the exception of LastValue aggregators. LastValue aggregators are required to maintain the last value across checkpoints.

Note that any Aggregator may be attached to any instrument--this is the result of the OpenTelemetry API/SDK separation. It is possible to attach a counter aggregator to a Measure instrument (to compute a simple sum) or a LastValue aggregator to a measure instrument (to compute the last value).

type Batcher ¶

type Batcher interface {
	// AggregationSelector is responsible for selecting the
	// concrete type of Aggregator used for a metric in the SDK.
	//
	// This may be a static decision based on fields of the
	// Descriptor, or it could use an external configuration
	// source to customize the treatment of each metric
	// instrument.
	//
	// The result from AggregatorSelector.AggregatorFor should be
	// the same type for a given Descriptor or else nil.  The same
	// type should be returned for a given descriptor, because
	// Aggregators only know how to Merge with their own type.  If
	// the result is nil, the metric instrument will be disabled.
	//
	// Note that the SDK only calls AggregatorFor when new records
	// require an Aggregator. This does not provide a way to
	// disable metrics with active records.
	AggregationSelector

	// Process is called by the SDK once per internal record,
	// passing the export Record (a Descriptor, the corresponding
	// Labels, and the checkpointed Aggregator).  The Batcher
	// should be prepared to process duplicate (Descriptor,
	// Labels) pairs during this pass due to race conditions, but
	// this will usually be the ordinary course of events, as
	// Aggregators are typically merged according the output set
	// of labels.
	//
	// The Context argument originates from the controller that
	// orchestrates collection.
	Process(ctx context.Context, record Record) error

	// CheckpointSet is the interface used by the controller to
	// access the fully aggregated checkpoint after collection.
	//
	// The returned CheckpointSet is passed to the Exporter.
	CheckpointSet() CheckpointSet

	// FinishedCollection informs the Batcher that a complete
	// collection round was completed.  Stateless batchers might
	// reset state in this method, for example.
	FinishedCollection()
}

Batcher is responsible for deciding which kind of aggregation to use (via AggregationSelector), gathering exported results from the SDK during collection, and deciding over which dimensions to group the exported data.

The SDK supports binding only one of these interfaces, as it has the sole responsibility of determining which Aggregator to use for each record.

The embedded AggregationSelector interface is called (concurrently) in instrumentation context to select the appropriate Aggregator for an instrument.

The `Process` method is called during collection in a single-threaded context from the SDK, after the aggregator is checkpointed, allowing the batcher to build the set of metrics currently being exported.

The `CheckpointSet` method is called during collection in a single-threaded context from the Exporter, giving the exporter access to a producer for iterating over the complete checkpoint.

type CheckpointSet ¶

type CheckpointSet interface {
	// ForEach iterates over aggregated checkpoints for all
	// metrics that were updated during the last collection
	// period. Each aggregated checkpoint returned by the
	// function parameter may return an error.
	// ForEach tolerates ErrNoData silently, as this is
	// expected from the Meter implementation. Any other kind
	// of error will immediately halt ForEach and return
	// the error to the caller.
	ForEach(func(Record) error) error
}

CheckpointSet allows a controller to access a complete checkpoint of aggregated metrics from the Batcher. This is passed to the Exporter which may then use ForEach to iterate over the collection of aggregated metrics.

type Exporter ¶

type Exporter interface {
	// Export is called immediately after completing a collection
	// pass in the SDK.
	//
	// The Context comes from the controller that initiated
	// collection.
	//
	// The CheckpointSet interface refers to the Batcher that just
	// completed collection.
	Export(context.Context, CheckpointSet) error
}

Exporter handles presentation of the checkpoint of aggregate metrics. This is the final stage of a metrics export pipeline, where metric data are formatted for a specific system.

type LabelEncoder ¶

type LabelEncoder interface {
	// Encode is called (concurrently) in instrumentation context.
	// It should return a unique representation of the labels
	// suitable for the SDK to use as a map key.
	//
	// The exported Labels object retains a reference to its
	// LabelEncoder to determine which encoding was used.
	//
	// The expectation is that Exporters with a pre-determined to
	// syntax for serialized label sets should implement
	// LabelEncoder, thus avoiding duplicate computation in the
	// export path.
	Encode(LabelIterator) string
}

LabelEncoder enables an optimization for export pipelines that use text to encode their label sets.

This interface allows configuring the encoder used in the SDK and/or the Batcher so that by the time the exporter is called, the same encoding may be used.

If none is provided, a default will be used.

type LabelIterator ¶

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

LabelIterator allows iterating over an ordered set of labels. The typical use of the iterator is as follows:

iter := export.NewLabelIterator(getStorage())
for iter.Next() {
  label := iter.Label()
  // or, if we need an index:
  // idx, label := iter.IndexedLabel()
  // do something with label
}

func NewLabelIterator ¶

func NewLabelIterator(storage LabelStorage) LabelIterator

NewLabelIterator creates an iterator going over a passed storage.

func (*LabelIterator) IndexedLabel ¶

func (i *LabelIterator) IndexedLabel() (int, core.KeyValue)

IndexedLabel returns current index and label. Must be called only after Next returns true.

func (*LabelIterator) Label ¶

func (i *LabelIterator) Label() core.KeyValue

Label returns current label. Must be called only after Next returns true.

func (*LabelIterator) Len ¶

func (i *LabelIterator) Len() int

Len returns a number of labels in the iterator's label storage.

func (*LabelIterator) Next ¶

func (i *LabelIterator) Next() bool

Next moves the iterator to the next label. Returns false if there are no more labels.

type LabelSlice ¶

type LabelSlice []core.KeyValue

LabelSlice implements LabelStorage in terms of a slice.

func (LabelSlice) GetLabel ¶

func (s LabelSlice) GetLabel(idx int) core.KeyValue

GetLabel is a part of LabelStorage implementation.

func (LabelSlice) Iter ¶

func (s LabelSlice) Iter() LabelIterator

Iter returns an iterator going over the slice.

func (LabelSlice) NumLabels ¶

func (s LabelSlice) NumLabels() int

NumLabels is a part of LabelStorage implementation.

type LabelStorage ¶

type LabelStorage interface {
	// NumLabels returns a number of labels in the storage.
	NumLabels() int
	// GetLabels gets a label from a passed index.
	GetLabel(int) core.KeyValue
}

LabelStorage provides an access to the ordered labels.

type Labels ¶

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

Labels stores complete information about a computed label set, including the labels in an appropriate order (as defined by the Batcher). If the batcher does not re-order labels, they are presented in sorted order by the SDK.

func NewLabels ¶

func NewLabels(storage LabelStorage, encoded string, encoder LabelEncoder) Labels

NewLabels builds a Labels object, consisting of an ordered set of labels, a unique encoded representation, and the encoder that produced it.

func (Labels) Encoded ¶

func (l Labels) Encoded() string

Encoded is a pre-encoded form of the ordered labels.

func (Labels) Encoder ¶

func (l Labels) Encoder() LabelEncoder

Encoder is the encoder that computed the Encoded() representation.

func (Labels) Iter ¶

func (l Labels) Iter() LabelIterator

Iter returns an iterator over ordered labels.

type Record ¶

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

Record contains the exported data for a single metric instrument and label set.

func NewRecord ¶

func NewRecord(descriptor *metric.Descriptor, labels Labels, aggregator Aggregator) Record

NewRecord allows Batcher implementations to construct export records. The Descriptor, Labels, and Aggregator represent aggregate metric events received over a single collection period.

func (Record) Aggregator ¶

func (r Record) Aggregator() Aggregator

Aggregator returns the checkpointed aggregator. It is safe to access the checkpointed state without locking.

func (Record) Descriptor ¶

func (r Record) Descriptor() *metric.Descriptor

Descriptor describes the metric instrument being exported.

func (Record) Labels ¶

func (r Record) Labels() Labels

Labels describes the labels associated with the instrument and the aggregated data.

Source Files ¶

metric.go

Directories ¶