Expand event-model description to more clearly delineate instrument v…

specification/metrics/datamodel.md

@@ -34,7 +34,7 @@ Prometheus Remote Write protocol without loss of features or semantics, through
 well-defined translations of the data, including the ability to automatically
 remove attributes and lower histogram resolution.
 
-## Events → Data → Timeseries
+## Events → Streams → Timeseries
 
 The OTLP Metrics protocol is designed as a standard for transporting metric
 data. To describe the intended use of this data and the associated semantic
@@ -43,7 +43,7 @@ containing a higher-level model, about Metrics APIs and discrete input values,
 and a lower-level model, defining the Timeseries and discrete output values.
 The relationship between models is displayed in the diagram below.
 
-![Events → Data → Timeseries Diagram](img/model-layers.png)
+![Events → Streams → Timeseries Diagram](img/model-layers.png)
 
 This protocol was designed to meet the requirements of the OpenCensus Metrics
 system, particularly to meet its concept of Metrics Views. Views are
@@ -146,26 +146,45 @@ OpenTelemetry fragments metrics into three interacting models:
 
 ### Event Model
 
-This specification uses as its foundation a
-[Metrics API consisting of 6 model instruments](api.md), each having distinct
-semantics, that were prototyped in several OpenTelemetry SDKs between July 2019
-and June 2020. The model instruments and their specific use-cases are meant to
-anchor our understanding of the OpenTelemetry data model and are divided into
-three categories:
-
-- Synchronous vs. Asynchronous. The act of calling a Metrics API in a
- synchronous context means the application/library calls the SDK, typically having
- associated trace context and baggage; an Asynchronous instrument is called at
- collection time, through a callback, and lacks context.
-- Adding vs. Grouping. Whereas adding instruments express a sum, grouping
- instruments characterize a group of measurements. The numbers passed to adding
- instruments define division, in the algebraic sense, while the numbers passed
- to grouping instruments are generally not. Adding instrument values are always
- parts of a sum, while grouping instrument values are individual measurements.
-- Monotonic vs. Non-Monotonic. The adding instruments are categorized by whether
- the derivative of the quantity they express is non-negative. Monotonic
- instruments are primarily useful for monitoring a rate value, whereas
- non-monotonic instruments are primarily useful for monitoring a total value.
+The event model is where recording of data happens. Its foundation is made of
+[Instruments](api.md), which are used to record data observations via events.
+These raw events are then transformed in some fashion before being sent to some
+other system. OpenTelemetry metrics are designed such that the same instrument
+and events can be used in different ways to generate metric streams.
+
+![Events → Streams](img/model-event-layer.png)
+
+Even though observation events could be reported directly to a backend, in
+practice this would be infeasible due to the sheer volume of data used in
+observability systems, and the limited amount of network/cpu telemetry
+collection resources available for telemetry collection purposes. The best
+example of this is the Histogram metric where raw events are recorded in a
+compressed format rather than individual timeseries.
+
+While OpenTelemetry provides flexibility in how instruments can be transformed
+into metric streams, the instruments are defined such that a reasonable default
+mapping can be provided.
+
+The [OpenTelemetry metric instruments](api.md) are designed around the
+following concerns:
+
+- Synchronous vs. Asynchronous collection.
+ - Synchronous instruments are those where an application/library records a
+ metric data point inline. In this scenario, OpenTelemetry *can* attach
+ context (e.g. baggage) to recorded data points.
+ - Asynchronous instruments are those where OpenTelemetry (not the application)
+ will execute a callback (or other similar mechanism) to pull data points
+ on demand. This is generally done at regular intervals.
+- Adding vs. Grouping aggregation.
+ - Adding instruments express a sum. All points recorded via this instrument
+ are parts of a whole.
+ - Grouping instruments characterize a group of measurements. All points
+ recorded via this instrument are individual measurements.
+- Monotonic vs. Non-Monotonic (adding instruments only). These instruments are
+ categorized by whether the derivative of the quantity they express is
+ non-negative.
+ - Monotonic instruments are primarily useful for monitoring a rate value.
+ - Non-monotonic instruments are primarily useful for monitoring a total value.
 
 In the Event model, the primary data are (instrument, number) points, originally
 observed in real time or on demand (for the synchronous and asynchronous cases,