Add more details to SDK MeterProvider and View

specification/metrics/sdk.md

@@ -33,12 +33,168 @@ Table of Contents
 
 ## MeterProvider
 
-TODO:
+### Meter Creation
+
+New `Meter` instances are always created through a `MeterProvider` (see
+[API](./api.md#meterprovider)). The `name`, `version` (optional), and
+`schema_url` (optional) arguments supplied to the `MeterProvider` MUST be used
+to create an
+[`InstrumentationLibrary`](https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md)
+instance which is stored on the created `Meter`.
+
+Configuration (i.e., [MeasurementProcessors](#measurementprocessor),
+[MetricProcessors](#metricprocessor), [MetricExporters](#metricexporter) and
+[`Views`](#view)) MUST be managed solely by the `MeterProvider` and it MUST
+provide some way to configure all of them that are implemented in the SDK, at
+least when creating or initializing it.
+
+The `MeterProvider` MAY provide methods to update the configuration. If
+configuration is updated (e.g., adding a `MetricProcessor`), the updated
+configuration MUST also apply to all already returned `Meters` (i.e. it MUST NOT
+matter whether a `Meter` was obtained from the `MeterProvider` before or after
+the configuration change). Note: Implementation-wise, this could mean that
+`Meter` instances have a reference to their `MeterProvider` and access
+configuration only via this reference.
+
+### Shutdown
+
+TODO
+
+### ForceFlush
+
+TODO
+
+### View
+
+`View` gives the SDK users flexibility to customize the metrics they want. Here
+are some examples when `View` is needed:
+
+* Customize which [Instrument](./api.md#instrument) to be processed/ignored. For
+  example, an [instrumented library](../glossary.md#instrumented-library) can
+  provide both temperature and humidity, but the application developer only
+  wants temperature information.
+* Customize the aggregation - if the default aggregation associated with the
+  Instrument does not meet the expectation. For example, an HTTP client library
+  might expose HTTP client request duration as [Histogram](./api.md#histogram)
+  by default, but the application developer only wants the total count of
+  outgoing requests.
+* Customize which attribute(s) to be reported as metrics dimension(s). For
+  example, an HTTP server library might expose HTTP verb (e.g. GET, POST) and
+  HTTP status code (e.g. 200, 301, 404). The application developer might only
+  care about HTTP status code (e.g. reporting the total count of HTTP requests
+  for each HTTP status code). There are also extreme scenario that the
+  application developer does not need any dimension (e.g. just get the total
+  count of all incoming requests).
+* Add additional dimension(s) from the [Context](../context/context.md). For
+  example, a [Baggage](../baggage/api.md) value might be available indicating
+  whether an HTTP request is coming from a bot/crawler or not. The application
+  developer might want this to be converted to a dimension for HTTP server
+  metrics (e.g. the request/second from bots vs. real users).
+
+The SDK MUST provide the means to register Views with a `MeterProvider`. Here
+are the inputs:
+
+* The Instrument selection criteria (required), which covers:
+  * The `name` of the Instrument(s), with wildcard support (required).
+  * The `name` of the Meter (optional).
+  * The `version` of the Meter (optional).
+  * The `schema_url` of the Meter (optional).
+  * Individual language client MAY choose to support more criteria. For example,
+    a strong typed language MAY support point type (e.g. allow the users to
+    select Instruments based on whether the underlying type is integer or
+    double).
+* The `name` of the View (optional). If not provided, the Instrument `name`
+  would be used by default. This will be used as the name of the [metrics
+  stream](./datamodel.md#events--data-stream--timeseries).
+* The configuration for the resulting [metrics
+  stream](./datamodel.md#events--data-stream--timeseries):
+  * The `description`. If not provided, the Instrument `description` would be
+    used by default.
+  * A list of `attribute keys` (optional). If not provided, all the attribute
+    keys will be used by default (TODO: once the Hint API is available, the
+    default behavior should respect the Hint if it is available).
+  * The `extra dimensions` which come from Baggage/Context (optional). If not
+    provided, no extra dimension will be used. Please note that this only
+    applies to [synchronous Instruments](./api.md#synchronous-instrument).
+  * The `aggregation` (optional) to be used. If not provided, a default
+    aggregation will be applied by the SDK. The default aggregation is a TODO
+    (e.g. first see if there is an explicitly specified aggregation from the
+    View, if not, see if there is a Hint, if not, fallback to the default
+    aggregation that is associated with the Instrument type), and for histogram,
+    the default buckets would be (-∞, 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, +∞).
+
+The SDK SHOULD use the following logic to determine how to process an
+Instrument:
+
+* Determine the `MeterProvider` which "owns" the Instrument.
+* If the `MeterProvider` has no `View` registered, take the Instrument and apply
+    the default configuration.
+* If the `MeterProvider` has one or more `View`(s) registered, for each View:
+  * If the Instrument could match the instrument selection criteria:
+    * Try to apply the View configuration. If there is an error (e.g. the View
+      asks for extra dimensions from the Baggage, but the Instrument is
+      [asynchronous](./api.md#asynchronous-instrument) which doesn't have
+      Context) or a conflict (e.g. the View requires to export the metrics using
+      a certain name, but the name is already used by another View), provide a
+      way to let the user know (e.g. expose [self-diagnostics
+      logs](../error-handling.md#self-diagnostics)).
+* END.
+
+Here are some examples:
+
+```python
+# Python
+'''
++------------------+
+| MeterProvider    |
+|   Meter A        |
+|     Counter X    |
+|     Histogram Y  |
+|   Meter B        |
+|     Gauge Z      |
++------------------+
+'''
+
+# metrics from X and Y (reported as Foo and Bar) will be exported
+meter_provider
+    .add_view("X")
+    .add_view("Foo", instrument_name="Y")
+    .add_view(
+        "Bar",
+        instrument_name="Y",
+        aggregation=HistogramAggregation(buckets=[5.0, 10.0, 25.0, 50.0, 100.0]))
+    .set_exporter(PrometheusExporter())
+```
+
+```python
+# all the metrics will be exported using the default configuration
+meter_provider.set_exporter(ConsoleExporter())
+```
 
-* Allow multiple pipelines (processors, exporters).
-* Configure "Views".
-* Configure timing (related to [issue
-  1432](https://github.com/open-telemetry/opentelemetry-specification/issues/1432)).
+```python
+# all the metrics will be exported using the default configuration
+meter_provider
+    .add_view("*") # a wildcard view that matches everything
+    .set_exporter(ConsoleExporter())
+```
+
+```python
+# Counter X will be exported as cumulative sum
+meter_provider
+    .add_view("X", aggregation=SumAggregation(CUMULATIVE))
+    .set_exporter(ConsoleExporter())
+```
+
+```python
+# Counter X will be exported as delta sum
+# Histogram Y and Gauge Z will be exported with 2 dimensions (a and b)
+meter_provider
+    .add_view("X", aggregation=SumAggregation(DELTA))
+    .add_view("*", attribute_keys=["a", "b"])
+    .set_exporter(ConsoleExporter())
+```
 
 ## MeasurementProcessor
 
@@ -69,13 +225,13 @@ active span](../trace/api.md#context-interaction)).
 +------------------+
 | MeterProvider    |                 +----------------------+            +-----------------+
 |   Meter A        | Measurements... |                      | Metrics... |                 |
-|     Instrument X |-----------------> MeasurementProcessor +------------> In-memory state |
-|     Instrument Y +                 |                      |            |                 |
+|     Instrument X +-----------------> MeasurementProcessor +------------> In-memory state |
+|     Instrument Y |                 |                      |            |                 |
 |   Meter B        |                 +----------------------+            +-----------------+
 |     Instrument Z |
 |     ...          |                 +----------------------+            +-----------------+
 |     ...          | Measurements... |                      | Metrics... |                 |
-|     ...          |-----------------> MeasurementProcessor +------------> In-memory state |
+|     ...          +-----------------> MeasurementProcessor +------------> In-memory state |
 |     ...          |                 |                      |            |                 |
 |     ...          |                 +----------------------+            +-----------------+
 +------------------+
@@ -95,20 +251,20 @@ in the SDK:
 ```text
 +-----------------+            +-----------------+            +-----------------------+
 |                 | Metrics... |                 | Metrics... |                       |
-> In-memory state | -----------> MetricProcessor | -----------> MetricExporter (push) |--> Another process
+| In-memory state +------------> MetricProcessor +------------> MetricExporter (push) +--> Another process
 |                 |            |                 |            |                       |
 +-----------------+            +-----------------+            +-----------------------+
 
 +-----------------+            +-----------------+            +-----------------------+
 |                 | Metrics... |                 | Metrics... |                       |
-> In-memory state |------------> MetricProcessor |------------> MetricExporter (pull) |--> Another process (scraper)
+| In-memory state +------------> MetricProcessor +------------> MetricExporter (pull) +--> Another process (scraper)
 |                 |            |                 |            |                       |
 +-----------------+            +-----------------+            +-----------------------+
 ```
 
 ## MetricExporter
 
-`MetricExporter` defines the interface that protocol-specific exporters must
+`MetricExporter` defines the interface that protocol-specific exporters MUST
 implement so that they can be plugged into OpenTelemetry SDK and support sending
 of telemetry data.