Documentation
¶
Index ¶
- Variables
- func DefaultAggregationSelector(ik InstrumentKind) sdkmetric.Aggregation
- func DefaultTemporalitySelector(InstrumentKind) sdkmetricdata.Temporality
- type AggregationSelector
- type Exporter
- type Instrument
- type InstrumentKind
- type ManualReader
- type ManualReaderOption
- type MeterProvider
- type Option
- type PeriodicReader
- type PeriodicReaderOption
- type Producer
- type Reader
- type ReaderOption
- type Stream
- type TemporalitySelector
- type View
Constants ¶
This section is empty.
Variables ¶
var ErrExporterShutdown = fmt.Errorf("exporter is shutdown")
ErrExporterShutdown is returned if Export or Shutdown are called after an Exporter has been Shutdown.
var ErrInstrumentName = errors.New("invalid instrument name")
ErrInstrumentName indicates the created instrument has an invalid name. Valid names must consist of 255 or fewer characters including alphanumeric, _, ., -, / and start with a letter.
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 InstrumentKind) sdkmetric.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, Observable Counter ⇨ Sum, UpDownCounter ⇨ Sum, Observable UpDownCounter ⇨ Sum, Observable Gauge ⇨ LastValue, Histogram ⇨ ExplicitBucketHistogram.
func DefaultTemporalitySelector ¶
func DefaultTemporalitySelector(InstrumentKind) sdkmetricdata.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(InstrumentKind) sdkmetric.Aggregation
AggregationSelector selects the aggregation and the parameters to use for that aggregation based on the InstrumentKind.
If the Aggregation returned is nil or DefaultAggregation, the selection from DefaultAggregationSelector will be used.
type Exporter ¶
type Exporter interface {
// Temporality returns the Temporality to use for an instrument kind.
//
// This method needs to be concurrent safe with itself and all the other
// Exporter methods.
Temporality(met.InstrumentKind) sdkmetricdata.Temporality
// Aggregation returns the Aggregation to use for an instrument kind.
//
// This method needs to be concurrent safe with itself and all the other
// Exporter methods.
Aggregation(met.InstrumentKind) met.Aggregation
// 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.
//
// The passed ResourceMetrics may be reused when the call completes. If an
// exporter needs to hold this data after it returns, it needs to make a
// copy.
Export(context.Context, *sdkmetricdata.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.
//
// This method needs to be concurrent safe.
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.
//
// This method needs to be concurrent safe.
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 Instrument ¶
type Instrument struct {
// Name is the human-readable identifier of the instrument.
Name string
// Description describes the purpose of the instrument.
Description string
// Kind defines the functional group of the instrument.
Kind InstrumentKind
// Unit is the unit of measurement recorded by the instrument.
Unit string
// Scope identifies the instrumentation that created the instrument.
Scope instrumentation.Scope
// contains filtered or unexported fields
}
Instrument describes properties an instrument is created with.
func (Instrument) IsEmpty ¶
func (i Instrument) IsEmpty() bool
IsEmpty returns if all Instrument fields are their zero-value.
type InstrumentKind ¶
type InstrumentKind uint8
InstrumentKind is the identifier of a group of instruments that all performing the same function.
const ( // InstrumentKindCounter identifies a group of instruments that record // increasing values synchronously with the code path they are measuring. InstrumentKindCounter InstrumentKind = 1 // InstrumentKindUpDownCounter identifies a group of instruments that // record increasing and decreasing values synchronously with the code path // they are measuring. InstrumentKindUpDownCounter InstrumentKind = 2 // InstrumentKindHistogram identifies a group of instruments that record a // distribution of values synchronously with the code path they are // measuring. InstrumentKindHistogram InstrumentKind = 3 // InstrumentKindObservableCounter identifies a group of instruments that // record increasing values in an asynchronous callback. InstrumentKindObservableCounter InstrumentKind = 4 // InstrumentKindObservableUpDownCounter identifies a group of instruments // that record increasing and decreasing values in an asynchronous // callback. InstrumentKindObservableUpDownCounter InstrumentKind = 5 // InstrumentKindObservableGauge identifies a group of instruments that // record current values in an asynchronous callback. InstrumentKindObservableGauge InstrumentKind = 6 // InstrumentKindGauge identifies a group of instruments that record // instantaneous values synchronously with the code path they are // measuring. InstrumentKindGauge InstrumentKind = 7 )
func (InstrumentKind) String ¶
func (i InstrumentKind) String() string
type ManualReader ¶
type ManualReader struct {
// contains filtered or unexported fields
}
ManualReader is a simple Reader that allows an application to read metrics on demand.
func NewManualReader ¶
func NewManualReader(opts ...ManualReaderOption) *ManualReader
NewManualReader returns a Reader which is directly called to collect metrics.
func (*ManualReader) Collect ¶
func (mr *ManualReader) Collect(ctx context.Context, rm *sdkmetricdata.ResourceMetrics) error
Collect gathers all metric data related to the Reader from the SDK and other Producers and stores the result in rm.
Collect will return an error if called after shutdown. Collect will return an error if rm is a nil ResourceMetrics. Collect will return an error if the context's Done channel is closed.
This method is safe to call concurrently.
func (*ManualReader) MarshalLog ¶
func (mr *ManualReader) MarshalLog() interface{}
MarshalLog returns logging data about the ManualReader.
type ManualReaderOption ¶
type ManualReaderOption interface {
// contains filtered or unexported methods
}
ManualReaderOption applies a configuration option value to a ManualReader.
func WithAggregationSelector ¶
func WithAggregationSelector(selector AggregationSelector) ManualReaderOption
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) ManualReaderOption
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 MeterProvider ¶
type MeterProvider struct {
embedded.MeterProvider
// 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.
ForceFlush calls ForceFlush(context.Context) error on all Readers that implements this method.
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.
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 ¶
WithReader associates Reader r with a MeterProvider.
By default, if this option is not used, the MeterProvider will perform no operations; no data will be exported without a Reader.
func WithResource ¶
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 PeriodicReader ¶
type PeriodicReader struct {
// contains filtered or unexported fields
}
PeriodicReader is a Reader that continuously collects and exports metric data at a set interval.
func NewPeriodicReader ¶
func NewPeriodicReader(exporter sdkmetric.Exporter, options ...PeriodicReaderOption) *PeriodicReader
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 any attempts that exceed 30 seconds, collect and export combined. The collect and export time are 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.
func (*PeriodicReader) Collect ¶
func (r *PeriodicReader) Collect(ctx context.Context, rm *sdkmetricdata.ResourceMetrics) error
Collect gathers all metric data related to the Reader from the SDK and other Producers and stores the result in rm. The metric data is not exported to the configured exporter, it is left to the caller to handle that if desired.
Collect will return an error if called after shutdown. Collect will return an error if rm is a nil ResourceMetrics. Collect will return an error if the context's Done channel is closed.
This method is safe to call concurrently.
func (*PeriodicReader) ForceFlush ¶
func (r *PeriodicReader) ForceFlush(ctx context.Context) error
ForceFlush flushes pending telemetry.
This method is safe to call concurrently.
func (*PeriodicReader) MarshalLog ¶
func (r *PeriodicReader) MarshalLog() interface{}
MarshalLog returns logging data about the PeriodicReader.
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.
This option overrides any value set for the OTEL_METRIC_EXPORT_INTERVAL environment variable.
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. This includes an export which occurs as part of Shutdown or ForceFlush if the user passed context does not have a deadline. If the user passed context does have a deadline, it will be used instead.
This option overrides any value set for the OTEL_METRIC_EXPORT_TIMEOUT environment variable.
If this option is not used or d is less than or equal to zero, 30 seconds is used as the default.
type Producer ¶
type Producer interface {
// Produce returns aggregated metrics from an external source.
//
// This method should be safe to call concurrently.
Produce(context.Context) ([]sdkmetricdata.ScopeMetrics, error)
}
Producer produces metrics for a Reader from an external source.
type Reader ¶
type Reader interface {
// Collect gathers and returns all metric data related to the Reader from
// the SDK and stores it in out. An error is returned if this is called
// after Shutdown or if out is nil.
//
// This method needs to be concurrent safe, and the cancellation of the
// passed context is expected to be honored.
Collect(ctx context.Context, rm *sdkmetricdata.ResourceMetrics) 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.
//
// This method needs to be concurrent safe.
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 exporter 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.
Warning: methods may be added to this interface in minor releases.
type ReaderOption ¶
type ReaderOption interface {
PeriodicReaderOption
ManualReaderOption
}
ReaderOption is an option which can be applied to manual or Periodic readers.
func WithProducer ¶
func WithProducer(p Producer) ReaderOption
WithProducer registers producers as an external Producer of metric data for this Reader.
type Stream ¶
type Stream struct {
// Name is the human-readable identifier of the stream.
Name string
// Description describes the purpose of the data.
Description string
// Unit is the unit of measurement recorded.
Unit string
// Aggregation the stream uses for an instrument.
Aggregation sdkmetric.Aggregation
// AttributeFilter is an attribute Filter applied to the attributes
// recorded for an instrument's measurement. If the filter returns false
// the attribute will not be recorded, otherwise, if it returns true, it
// will record the attribute.
//
// Use NewAllowKeysFilter from "go.opentelemetry.io/otel/attribute" to
// provide an allow-list of attribute keys here.
AttributeFilter attribute.Filter
}
Stream describes the stream of data an instrument produces.
type TemporalitySelector ¶
type TemporalitySelector func(InstrumentKind) sdkmetricdata.Temporality
TemporalitySelector selects the temporality to use based on the InstrumentKind.
type View ¶
type View func(Instrument) (Stream, bool)
View is an override to the default behavior of the SDK. It defines how data should be collected for certain instruments. It returns true and the exact Stream to use for matching Instruments. Otherwise, if the view does not match, false is returned.
func NewView ¶
func NewView(criteria Instrument, mask Stream) View
NewView returns a View that applies the Stream mask for all instruments that match criteria. The returned View will only apply mask if all non-zero-value fields of criteria match the corresponding Instrument passed to the view. If no criteria are provided, all field of criteria are their zero-values, a view that matches no instruments is returned. If you need to match a zero-value field, create a View directly.
The Name field of criteria supports wildcard pattern matching. The "*" wildcard is recognized as matching zero or more characters, and "?" is recognized as matching exactly one character. For example, a pattern of "*" matches all instrument names.
The Stream mask only applies updates for non-zero-value fields. By default, the Instrument the View matches against will be use for the Name, Description, and Unit of the returned Stream and no Aggregation or AttributeFilter are set. All non-zero-value fields of mask are used instead of the default. If you need to zero out an Stream field returned from a View, create a View directly.
Source Files
Directories