1
0
mirror of https://github.com/open-telemetry/opentelemetry-go.git synced 2024-12-10 09:50:58 +02:00

Document public metric SDK interfaces to remain stable (#4396)

* Document public ifaces to remain stable

Resolve #3673

* Revert changes to aggregation pkg

* Document reader as an interface that can be extended

* Address feedback

---------

Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com>
Co-authored-by: Robert Pająk <pellared@hotmail.com>
This commit is contained in:
Tyler Yahn 2023-09-06 13:55:56 -07:00 committed by GitHub
parent 01d64c3e77
commit 76c370f1b1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 21 additions and 0 deletions

View File

@ -33,12 +33,16 @@ type Exporter interface {
// This method needs to be concurrent safe with itself and all the other
// Exporter methods.
Temporality(InstrumentKind) metricdata.Temporality
// DO NOT CHANGE: any modification will not be backwards compatible and
// must never be done outside of a new major release.
// 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(InstrumentKind) Aggregation
// DO NOT CHANGE: any modification will not be backwards compatible and
// must never be done outside of a new major release.
// Export serializes and transmits metric data to a receiver.
//
@ -55,6 +59,8 @@ type Exporter interface {
// exporter needs to hold this data after it returns, it needs to make a
// copy.
Export(context.Context, *metricdata.ResourceMetrics) error
// DO NOT CHANGE: any modification will not be backwards compatible and
// must never be done outside of a new major release.
// ForceFlush flushes any metric data held by an exporter.
//
@ -63,6 +69,8 @@ type Exporter interface {
//
// This method needs to be concurrent safe.
ForceFlush(context.Context) error
// DO NOT CHANGE: any modification will not be backwards compatible and
// must never be done outside of a new major release.
// Shutdown flushes all metric data held by an exporter and releases any
// held computational resources.
@ -75,4 +83,6 @@ type Exporter interface {
//
// This method needs to be concurrent safe.
Shutdown(context.Context) error
// DO NOT CHANGE: any modification will not be backwards compatible and
// must never be done outside of a new major release.
}

View File

@ -50,6 +50,8 @@ var errNonPositiveDuration = fmt.Errorf("non-positive duration")
//
// 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 Reader interface {
// register registers a Reader with a MeterProvider.
// The producer argument allows the Reader to signal the sdk to collect
@ -75,6 +77,8 @@ type Reader interface {
// This method needs to be concurrent safe, and the cancelation of the
// passed context is expected to be honored.
Collect(ctx context.Context, rm *metricdata.ResourceMetrics) error
// DO NOT CHANGE: any modification will not be backwards compatible and
// must never be done outside of a new major release.
// Shutdown flushes all metric measurements held in an export pipeline and releases any
// held computational resources.
@ -89,6 +93,8 @@ type Reader interface {
//
// This method needs to be concurrent safe.
Shutdown(context.Context) error
// DO NOT CHANGE: any modification will not be backwards compatible and
// must never be done outside of a new major release.
}
// sdkProducer produces metrics for a Reader.
@ -101,10 +107,15 @@ type sdkProducer interface {
// Producer produces metrics for a Reader from an external source.
type Producer interface {
// DO NOT CHANGE: any modification will not be backwards compatible and
// must never be done outside of a new major release.
// Produce returns aggregated metrics from an external source.
//
// This method should be safe to call concurrently.
Produce(context.Context) ([]metricdata.ScopeMetrics, error)
// DO NOT CHANGE: any modification will not be backwards compatible and
// must never be done outside of a new major release.
}
// produceHolder is used as an atomic.Value to wrap the non-concrete producer