From 76c370f1b128a0dab2d456f0fc26b59c4595fb36 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 6 Sep 2023 13:55:56 -0700 Subject: [PATCH] Document public metric SDK interfaces to remain stable (#4396) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 Co-authored-by: Robert Pająk --- sdk/metric/exporter.go | 10 ++++++++++ sdk/metric/reader.go | 11 +++++++++++ 2 files changed, 21 insertions(+) diff --git a/sdk/metric/exporter.go b/sdk/metric/exporter.go index 695cf466c0e..da8941b378d 100644 --- a/sdk/metric/exporter.go +++ b/sdk/metric/exporter.go @@ -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. } diff --git a/sdk/metric/reader.go b/sdk/metric/reader.go index 6ad9680413b..44e09fb355d 100644 --- a/sdk/metric/reader.go +++ b/sdk/metric/reader.go @@ -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