Skip to content

Commit

Permalink
Document public metric SDK interfaces to remain stable (#4396)
Browse files Browse the repository at this point in the history
* 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>
  • Loading branch information
3 people authored Sep 6, 2023
1 parent 01d64c3 commit 76c370f
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 0 deletions.
10 changes: 10 additions & 0 deletions sdk/metric/exporter.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
//
Expand All @@ -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.
//
Expand All @@ -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.
Expand All @@ -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.
}
11 changes: 11 additions & 0 deletions sdk/metric/reader.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand Down

0 comments on commit 76c370f

Please sign in to comment.