Comments

sdk/export/metric/aggregation/aggregation.go

@@ -25,9 +25,12 @@ import (
 // Aggregation.
 
 type (
-	// Aggregation is one of the interfaces below.
+	// Aggregation is an interface returned by the Aggregator
+	// containing an interval of metric data.
 	Aggregation interface {
-		// Kind returns the kind of aggregation used.
+		// Kind returns a short identifying string to identify
+		// the Aggregator that was used to produce the
+		// Aggregation (e.g., "sum").
 		Kind() Kind
 	}
 
@@ -105,6 +108,19 @@ type (
 )
 
 type (
+	// Kind is a short name for the Aggregator that produces an
+	// Aggregation, used for descriptive purpose only.  Kind is a
+	// string to allow user-defined Aggregators.
+	//
+	// When deciding how to handle an Aggregation, Exporters are
+	// encouraged to decide based on conversion to the above
+	// interfaces based on strength, not on Kind value, when
+	// deciding how to expose metric data.  This enables
+	// user-supplied Aggregators to replace builtin Aggregators.
+	//
+	// For example, test for a Distribution before testing for a
+	// MinMaxSumCount, test for a Histogram before testing for a
+	// Sum, and so on.
 	Kind string
 )
 
@@ -130,7 +146,7 @@ var (
 	ErrNoData = fmt.Errorf("no data collected by this aggregator")
 )
 
-// String returns a string representation of the aggregation kind.
+// String returns the string value of Kind.
 func (k Kind) String() string {
 	return string(k)
 }