Introduce the Metrics data model. (#118)

Author: g-easy

stats/Export.md

@@ -28,6 +28,9 @@ parameter from the `View` and the aggregated data associated with those `columns
 
 The library SHOULD provide a means of retrieving the ViewData for any registered view in the system.
 
+ViewData is a language-specific data structure implementing the [Metrics data
+model](Metrics.md).
+
 ### Aggregation to Metric
 
 | Aggregation  | Measure Type    | Metric Type  | Value Type   | Unit               |
@@ -39,4 +42,4 @@ The library SHOULD provide a means of retrieving the ViewData for any registered
 | LastValue    | Int64           | GAUGE        | INT64        | Measure Unit       |
 | Distribution | Int64 or Double | CUMULATIVE   | DISTRIBUTION | Measure Unit       |
 
-Dimensionless Unit can be represented as "1".
+Dimensionless Unit can be represented as "1".

stats/Metrics.md

@@ -0,0 +1,21 @@
+# Metrics
+Metrics are a data model for what stats exporters take as input.
+
+Different exporters have different capabilities (e.g. which data types
+are supported) and different constraints (e.g. which characters are allowed in
+label keys). Metrics is intended to be a superset of what's possible, not a
+lowest common denominator that's supported everywhere.
+
+Because of this, Metrics puts minimal constraints on the data (e.g. which
+characters are allowed in keys), and code dealing with Metrics should avoid
+validation and sanitization of the Metrics data. Instead, pass the data to the
+backend, rely on the backend to perform validation, and pass back any errors
+from the backend.
+
+The Metrics data model is defined as
+[metrics.proto](https://github.com/census-instrumentation/opencensus-proto/blob/master/opencensus/proto/stats/metrics/metrics.proto),
+but the proto is just to illustrate the concepts. OpenCensus implementations
+don't have to use the actual proto, and can instead use a language-specific
+in-memory data structure that captures what exporters need. This structure
+should use the names and fields from the data model, for API consistency across
+languages.

stats/README.md

@@ -13,7 +13,8 @@ metrics.
 data aggregation.
 * [Export API](Export.md): used by the specific vendors to define vendor specific exporters (e.g.
 Prometheus, Stackdriver, SignalFx).
+* [Metrics Data Model](Metrics.md): defines a data model for exporters.
 
 ## Utils
 * [HTTP integration](HTTP.md): document about how to instrument http frameworks.
-* [gRPC integration](gRPC.md): document about how to instrument gRPC framework.
+* [gRPC integration](gRPC.md): document about how to instrument gRPC framework.