Add more details to SDK MeterProvider and View

specification/metrics/sdk.md

@@ -33,10 +33,141 @@ Table of Contents
 
 ## MeterProvider
 
+### 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 `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 Instrument selection criteria (required), which covers:
+  * The `name` of the Meter (optional).
+  * The `version` of the Meter (optional).
+  * The `schema_url` of the Meter (optional).
+  * The `name` of the Instrument (required).
+  * Individual language client MAY choose to support more criteria.
+* 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.
+  * The `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), any
+    `extra dimensions` configured on [asynchronous
+    Instruments](./api.md#asynchronous-instrument) will be considered as error.
+  * 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, 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 consider the following situation as user error and provide a way
+to let the user know (e.g. expose [self-diagnostics
+logs](../error-handling.md#self-diagnostics)):
+
+* If there are more than one Instruments meeting the selection criteria.
+* If the name of the View has conflict with other Views.
+
+If there is no View registered, all the Instruments associated with the
+MeterProvider SHOULD be used.
+
+If there is any View registered, only the registered View(s) SHOULD be used.
+
+Here is one example:
+
+```python
+# Python
+'''
++------------------+
+| MeterProvider    |
+|   Meter A        |
+|     Counter X    |
+|     Histogram Y  |
+|   Meter B        |
+|     Gauge Z      |
++------------------+
+'''
+
+meter_provider.start_pipeline(
+    # metrics from X, Y and Z will be exported to console every 5 seconds (default)
+    pipeline: pipeline
+        .add_exporter(ConsoleExporter())
+).start_pipeline(
+    # metrics from X and Y (reported as Foo and Bar) will be exported to Prometheus upon scraping
+    pipeline: pipeline
+        .add_view(name="X")
+        .add_view(name="Foo", instrument_name="Y")
+        .add_view(name="Bar", instrument_name="Y")
+        .add_exporter(PrometheusExporter())
+)
+```
+
 TODO:
 
-* Allow multiple pipelines (processors, exporters).
-* Configure "Views".
+* Support multiple pipelines (processors, exporters).
 * Configure timing (related to [issue
   1432](https://github.com/open-telemetry/opentelemetry-specification/issues/1432)).
 
@@ -108,7 +239,7 @@ in the SDK:
 
 ## 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.