Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AggregationSelector ¶
type AggregationSelector interface {
// AggregatorFor allocates a variable number of aggregators of
// a kind suitable for the requested export. This method
// initializes a `...*Aggregator`, to support making a single
// allocation.
//
// When the call returns without initializing the *Aggregator
// to a non-nil value, the metric instrument is explicitly
// disabled.
//
// This must return a consistent type to avoid confusion in
// later stages of the metrics export process, i.e., when
// Merging or Checkpointing 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 be called
// concurrently.
//
// 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 a `correlation.Map` or `trace.SpanContext`.
Update(context.Context, metric.Number, *metric.Descriptor) error
// SynchronizedCopy is called during collection to finish one
// period of aggregation by atomically saving the
// currently-updating state into the argument Aggregator.
//
// SynchronizedCopy() is called concurrently with Update(). These
// two methods must be synchronized with respect to each
// other, for correctness.
//
// After saving a synchronized copy, the Aggregator can be converted
// into one or more of the interfaces in the `aggregation` sub-package,
// according to kind of Aggregator that was selected.
//
// This method will return an InconsistentAggregatorError if
// this Aggregator cannot be copied into the destination due
// to an incompatible type.
//
// This call has no Context argument because it is expected to
// perform only computation.
SynchronizedCopy(destination Aggregator, descriptor *metric.Descriptor) error
// Merge combines the checkpointed state from the argument
// Aggregator into this Aggregator. Merge is not synchronized
// with respect to Update or SynchronizedCopy.
//
// The owner of an Aggregator being merged is responsible for
// synchronization of both Aggregator states.
Merge(Aggregator, *metric.Descriptor) error
}
Aggregator implements a specific aggregation behavior, e.g., a behavior to track a sequence of updates to an instrument. Sum-only instruments commonly use a simple Sum aggregator, but for the distribution instruments (ValueRecorder, ValueObserver) there are a number of possible aggregators with different cost and accuracy tradeoffs.
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 Sum aggregator to a ValueRecorder instrument or a MinMaxSumCount aggregator to a Counter instrument.
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
// Locker supports locking the checkpoint set. Collection
// into the checkpoint set cannot take place (in case of a
// stateful integrator) while it is locked.
//
// The Integrator attached to the Accumulator MUST be called
// with the lock held.
sync.Locker
// RLock acquires a read lock corresponding to this Locker.
RLock()
// RUnlock releases a read lock corresponding to this Locker.
RUnlock()
}
CheckpointSet allows a controller to access a complete checkpoint of aggregated metrics from the Integrator. 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 Integrator 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 Integrator ¶
type Integrator 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). This call has no
// Context argument because it is expected to perform only
// computation. An SDK is not expected to call exporters from
// with Process, use a controller for that (see
// ./controllers/{pull,push}.
Process(record Record) error
}
Integrator 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 integrator to build the set of metrics currently being exported.
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 *label.Set, resource *resource.Resource, aggregator Aggregator) Record
NewRecord allows Integrator 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