Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IteratorToSlice ¶ added in v0.3.0
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.
func NewLabelEncoderID ¶ added in v0.4.0
func NewLabelEncoderID() int64
NewLabelEncoderID returns a unique label encoder ID. It should be called once per each type of label encoder. Preferably in init() or in var definition.
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 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.
//
// The expectation is that when setting up an export pipeline
// both the batcher and the exporter will use the same label
// encoder to avoid the duplicate computation of the encoded
// labels in the export path.
Encode(LabelIterator) string
// ID should return a unique positive number associated with
// the label encoder. Stateless label encoders could return
// the same number regardless of an instance, stateful label
// encoders should return a number depending on their state.
ID() int64
}
LabelEncoder enables an optimization for export pipelines that use text to encode their label sets.
This interface allows configuring the encoder used in the Batcher so that by the time the exporter is called, the same encoding may be used.
func NewDefaultLabelEncoder ¶ added in v0.4.0
func NewDefaultLabelEncoder() LabelEncoder
NewDefaultLabelEncoder returns a label encoder that encodes labels in such a way that each escaped label's key is followed by an equal sign and then by an escaped label's value. All key-value pairs are separated by a comma.
Escaping is done by prepending a backslash before either a backslash, equal sign or a comma.
type LabelIterator ¶ added in v0.3.0
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 ¶ added in v0.3.0
func NewLabelIterator(storage LabelStorage) LabelIterator
NewLabelIterator creates an iterator going over a passed storage.
func (*LabelIterator) IndexedLabel ¶ added in v0.3.0
func (i *LabelIterator) IndexedLabel() (int, core.KeyValue)
IndexedLabel returns current index and label. Must be called only after Next returns true.
func (*LabelIterator) Label ¶ added in v0.3.0
func (i *LabelIterator) Label() core.KeyValue
Label returns current label. Must be called only after Next returns true.
func (*LabelIterator) Len ¶ added in v0.3.0
func (i *LabelIterator) Len() int
Len returns a number of labels in the iterator's label storage.
func (*LabelIterator) Next ¶ added in v0.3.0
func (i *LabelIterator) Next() bool
Next moves the iterator to the next label. Returns false if there are no more labels.
type LabelSlice ¶ added in v0.3.0
LabelSlice implements LabelStorage in terms of a slice.
func (LabelSlice) GetLabel ¶ added in v0.3.0
func (s LabelSlice) GetLabel(idx int) core.KeyValue
GetLabel is a part of LabelStorage implementation.
func (LabelSlice) Iter ¶ added in v0.3.0
func (s LabelSlice) Iter() LabelIterator
Iter returns an iterator going over the slice.
func (LabelSlice) NumLabels ¶ added in v0.3.0
func (s LabelSlice) NumLabels() int
NumLabels is a part of LabelStorage implementation.
type LabelStorage ¶ added in v0.3.0
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 interface {
Iter() LabelIterator
Encoded(LabelEncoder) string
}
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 NewSimpleLabels ¶ added in v0.4.0
func NewSimpleLabels(encoder LabelEncoder, kvs ...core.KeyValue) Labels
NewSimpleLabels builds a Labels object, consisting of an ordered set of labels in a provided slice and a unique encoded representation generated by the passed encoder.
type NoopLabelEncoder ¶ added in v0.4.0
type NoopLabelEncoder struct{}
NoopLabelEncoder does no encoding at all.
func (NoopLabelEncoder) Encode ¶ added in v0.4.0
func (NoopLabelEncoder) Encode(LabelIterator) string
Encode is a part of an implementation of the LabelEncoder interface. It returns an empty string.
func (NoopLabelEncoder) ID ¶ added in v0.4.0
func (NoopLabelEncoder) ID() int64
ID is a part of an implementation of the LabelEncoder interface.
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.
Source Files
Directories