Rename metric instrument "Handles" to "Bound Instruments" (open-telem…

…etry/oteps#70)

* Add Bound Instruments OTEP

* Add status

oteps/0070-metric-bound-instrument.md

@@ -0,0 +1,63 @@
+# Rename metric instrument Handles to "Bound Instruments"
+
+*Status: proposed 11/26/2019*
+
+The OpenTelemetry metrics API specification refers to a concept known
+as ["metric handles"](0009-metric-handles.md), which is a metric
+instrument bound to a `LabelSet`.  This OTEP proposes to change that
+term to "bound instruments" to avoid the more-generic term "handle".
+
+The corresponding method to create a bound instrument will be renamed
+"Bind" as opposed to "GetHandle".
+
+## Motivation
+
+The term "Handle" is widely seen as too general for its purpose in the
+metrics API.  Rather than re-use a widely-used noun for this concept,
+we instead will re-use the metric "instrument" noun and apply an
+adjective, "bound" to convey that it has been bound to a `LabelSet`.
+
+## Explanation
+
+"Handle" has been confusing from the start. However it was preceded by
+other potentially confusing terms (e.g., "TimeSeries", "Entry").  The
+term "Bound instrument" was initially suggested
+[here](https://github.com/open-telemetry/opentelemetry-specification/pull/299#discussion_r334211154)
+and widely accepted.
+
+## Internal details
+
+This is a simple renaming.  All uses of "handle" will be replaced by
+"bound instrument" in the specification.  All uses of the `GetHandle`
+method become `Bind`.
+
+Note that the phrase "bound instrument" may not appear directly in the
+user-facing API, nor is it required to, whereas the method `GetHandle`
+is a specified method on metric instruments.
+
+The newly-named `Bind()` method returns a bound instrument type.  The
+name of the returned type may simply take the name of its instrument
+with the prefix `Bound`.  For example, an `Int64Counter` instrument's
+`Bind()` method should return a `BoundInt64Counter` type.
+
+As usual, the spelling and capitalization of these names are just
+recommendations, individual language committees should select names
+that are well suited to their language and existing API style.
+
+## Trade-offs and mitigations
+
+This is widely seen as an improvement, based on informal discussions.
+
+## Prior art and alternatives
+
+The OpenCensus libraries named this concept "Entries", with a
+`GetEntry` method, as they are entries some kind of map.
+
+The earliest appearance in OpenTelemetry renamed these "TimeSeries",
+hoping to improve matters, but "TimeSeries" more commonly refers to
+the output the bound instruments, after aggregation.  "Handle" was
+decided upon in an August 2019 working group on metrics.
+
+The Prometheus library refers to unbound instruments as "Vectors" and
+supports a variety of "With" methods to bind labels with the vector to
+yield a bound instrument.