Metrics terminology (#121)

Metrics terminology

terminology.md

@@ -104,7 +104,82 @@ Trace instead of trusting incoming Trace context.
 
 ## Metrics
 
-TODO: Describe metrics terminology https://github.com/open-telemetry/opentelemetry-specification/issues/45
+OpenTelemetry allows to record raw measurements or metrics with predefined
+aggregation and set of labels.
+
+Recording raw measurements using OpenTelemetry API allows to defer to end-user
+the decision on what aggregation algorithm should be applied for this metric as
+well as defining labels (dimensions). It will be used in client libraries like
+gRPC to record raw measurements "server_latency" or "received_bytes". So end
+user will decide what type of aggregated values should be collected out of these
+raw measurements. It may be simple average or elaborate histogram calculation.
+
+Recording of metrics with the pre-defined aggregation using OpenTelemtry API is
+not less important. It allows to collect values like cpu and memory usage, or
+simple metrics like "queue length".
+
+### Recording raw measurements
+
+The main classes used to record raw measurements are `Measure` and
+`Measurement`. List of `Measurement`s alongside the additional context can be
+recorded using OpenTelemetry API. So user may define to aggregate those
+`Measurement`s and use the context passed alongside to define additional
+dimensions of the resulting metric.
+
+#### Measure
+
+`Measure` describes the type of the individual values recorded by a library. It
+defines a contract between the library exposing the measurements and an
+application that will aggregate those individual measurements into a `Metric`.
+`Measure` is identified by name, description and a unit of values.
+
+#### Measurement
+
+`Measurement` describes a single value to be collected for a `Measure`.
+`Measurement` is an empty interface in API surface. This interface is defined in
+SDK.
+
+### Recording metrics with predefined aggregation
+
+The base class for all types of pre-aggregated metrics is called `Metric`. It
+defines basic metric properties like a name and labels. Classes inheriting from
+the `Metric` define their aggregation type as well as a structure of individual
+measurements or Points. API defines the following types of pre-aggregated
+metrics:
+
+- Counter metric to report instantaneous measurement. Counter values can go
+  up or stay the same, but can never go down. Counter values cannot be
+  negative. There are two types of counter metric values - `double` and `long`.
+- Gauge metric to report instantaneous measurement of a double value. Gauges can
+  go both up and down. The gauges values can be negative. There are two types of
+  gauge metric values - `double` and `long`.
+
+API allows to construct the `Metric` of a chosen type. SDK defines the way to
+query the current value of a `Metric` to be exported.
+
+Every type of a `Metric` has it's API to record values to be aggregated. API
+supports both - push and pull model of setting the `Metric` value.
+
+### Metrics data model and SDK
+
+Metrics data model is defined in SDK and is based on
+[metrics.proto](https://github.com/open-telemetry/opentelemetry-proto/blob/master/src/opentelemetry/proto/metrics/v1/metrics.proto).
+This data model is used by all the OpenTelemetry exporters as an 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. All exporters consume data from
+Metrics Data Model via a Metric Producer interface defined in OpenTelemetry SDK.
+
+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.
+
+OpenTelemetry defines the naming convention for metric names as well as a
+well-known metric names in [Semantic Conventions](semantic-conventions.md)
+document.
 
 ## DistributedContext
 

work_in_progress/specification/metrics/Metrics.md

@@ -1,21 +0,0 @@
-# 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/src/opencensus/proto/metrics/v1/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.

work_in_progress/specification/metrics/README.md

@@ -1,8 +0,0 @@
-# OpenCensus Library Metrics Package
-This documentation serves to document the "look and feel" of the open source metrics package. It 
-describes the key types and the overall behavior.
-
-Note: This is an experimental package and is likely to get backwards-incompatible updates in the future.
-
-## Main APIs
-* [Metrics Data Model](Metrics.md): defines the metrics data model.