Add details for Aggregator in Metrics Spec.

specification/metrics/sdk.md

@@ -207,6 +207,148 @@ meter_provider
     .set_exporter(ConsoleExporter())
 ```
 
+## Aggregator
+
+An `Aggregator` computes incoming Instrument [Measurements](./api.md#measurement)
+into [Aggregated Metrics](./datamodel.md#opentelemetry-protocol-data-model).
+
+The [View](./sdk.md#view) informs the SDK on creation and configuration of
+Aggregators. An [Aggregator Name](./sdk.md#aggregator-name) may be used to
+refer to an Aggregator and configuration.
+
+Implementors may choose the best idiomatic practice for their language to
+represent the semantic of an Aggregator and configuration parameters.
+
+e.g. The View specifies an Aggregator by string name (i.e. "Histogram").
+
+```python
+# Use Histogram with custom boundaries
+meter_provider
+  .add_view(
+    "X", 
+    aggregator="Histogram", 
+    aggregator_params={"Boundaries": [0, 10, 100]}
+    )
+```
+
+e.g. The View specifies an Aggregator by class/type instance.
+
+```c#
+// Use Histogram with custom boundaries
+meterProviderBuilder
+  .AddView(
+    instrumentName: "X",
+    aggregator: new HistogramAggregator(
+      boundaries: new double[] { 0.0, 10.0, 100.0 }
+    )
+  );
+```
+
+The [View](./sdk.md#view) informs the SDK to provide correct
+Instrument [Measurements](./api.md#measurement) to the correct Aggregators.
+
+An `Aggregator` is created with optional configuration parameters
+(i.e. Temporality=Delta, Boundaries=[0, 10, 100]).
+Default configuration parameters will be used unless overridden by
+optional configuration parameters.
+
+An `Aggregator` has a means to "update" its internal state with incoming
+Instrument [Measurement](./api.md#measurement) data.
+
+An `Aggregator` has a means to "collect"
+[Aggregated Metric](./datamodel.md#timeseries-model) data.
+The "collect" action should be treated as stateful and may update its
+internal state.
+
+**TBD**:
+The [View](./sdk.md#view) may inform an `Aggregator` to collect
+[Examplars](./datamodel.md#exemplars).
+
+### Aggregator Name
+
+The [View](./sdk.md#view) can refer to the following Aggregator by name.
+
+| Name | Aggregator | Description |
+| --- | --- | -- |
+| None | - | The reserved name "None" specify no Aggregator or a "virtual" Aggregator which ignores all measurements. |
+| Default | [Default](./sdk.md#default-aggregator) | The reserved name "Default" select an Aggregator by Instrument Kind. See [Default Aggregator](./sdk.md#default-aggregator). |
+| Sum | [Sum Aggregator](./sdk.md#sum-aggregator) | The reserved name "Sum" select a Sum Aggregator and SumType configuration parameter by Instrument Kind. See [Default Aggregator](./sdk.md#default-aggregator). |
+| Gauge | [Last Value Aggregator](./sdk.md#last-value-aggregator) | The reserved name "Gauge" select the [Last Value Aggregator](./sdk.md#last-value-aggregator). |
+| Histogram | "Best" Histogram | The reserved name "Histogram" select the "best" available Histogram Aggregator. i.e. [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator). |
+| Explicit_Bucket_Histogram | [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator) | Select the [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator). |
+
+### Default Aggregator
+
+The SDK MUST provide default Aggregators to support the
+[Metric Points](./datamodel.md#metric-points) in the
+[Metrics Data Model](./datamodel.md).
+
+The "Default" Aggregator uses the Instrument Kind (e.g. at View registration)
+to select an Aggregator and configuration parameters.
+
+| Instrument Kind | Default Aggregator | Configuration Parameters |
+| --- | --- | --- |
+| [Counter](./api.md#counter) | [Sum Aggregator](./sdk.md#sum-aggregator) | SumType = Monotonic |
+| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregator](./sdk.md#sum-aggregator) | SumType = Monotonic |
+| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregator](./sdk.md#sum-aggregator) | SumType = Non-Monotonic |
+| [Asynchrounous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregator](./sdk.md#sum-aggregator) | SumType = Non-Monotonic |
+| [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregator](./sdk.md#last-value-aggregator) | - |
+| [Histogram](./api.md#histogram) | "Best" Histogram<sup>1</sup> | - |
+
+\[1\]: The SDK will select the "best" available Histogram Aggregator. i.e. [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator).
+
+### Last Value Aggregator
+
+The Last Value Aggregator collects data for the
+[Gauge Metric Point](./datamodel.md#gauge).
+
+This Aggregator does not have any configuration parameters.
+
+This Aggregator collects:
+
+- The last `Measurement`.
+- The timestamp of the last `Measurement`.
+
+### Sum Aggregator
+
+The Sum Aggregator collects data for the [Sum Metric Point](./datamodel.md#sums).
+
+This Aggregator honors the following configuration parameters:
+
+| Key | Value | Default Value | Description |
+| --- | --- | --- | --- |
+| SumType<sup>2</sup> | Monotonic, Non-Monotonic, Other<sup>2</sup> | Depends<sup>1</sup> | See SumType<sup>2</sup> |
+| Temporality | Delta, Cummulative | Cummulative | See [Temporality](./datamodel.md#temporality). |
+
+\[1\]: Depends on the Instrument Kind. See [Default Aggregator](./sdk.md#default-aggregator).
+
+\[2\]: **TBD**: See [PR#320](open-telemetry/opentelemetry-proto#320) for SumType definition.
+
+This Aggregator collects:
+
+- The arithmetic sum of `Measurement` values.
+
+### Explicit Bucket Histogram Aggregator
+
+The Explicit Bucket Histogram Aggregator collects data for the
+[Histogram Metric Point](./datamodel.md#histogram). It supports a set of
+explicit boundary values for histogram bucketing.
+
+This Aggregator honors the following configuration parameters:
+
+| Key | Value | Default Value | Description |
+| --- | --- | --- | --- |
+| Monotonic | boolean | true | if true, non-positive values are treated as errors<sup>1</sup>. |
+| Temporality | Delta, Cummulative | Cummulative | See [Temporality](./datamodel.md#temporality). |
+| Boundaries | double\[\] | [ 0, 5, 10, 25, 50, 75, 100, 250, 500, 1000 ] | Array of increasing values representing explicit bucket boundary values.<br><br>The Default Value represents the following buckets:<br>(-&infin;, 0], (0, 5.0], (5.0, 10.0], (10.0, 25.0], (25.0, 50.0], (50.0, 75.0], (75.0, 100.0], (100.0, 250.0], (250.0, 500.0], (500.0, 1000.0], (1000.0, +&infin;) |
+
+\[1\]: Language implementations may choose the best strategy for handling errors. (i.e. Log, Discard, etc...)
+
+This Aggregator collects:
+
+- Count of `Measurement` values falling within explicit bucket boundaries.
+- Arithmetic sum of `Measurement` values in population.
+
 ## MeasurementProcessor
 
 `MeasurementProcessor` is an interface which allows hooks when a