From 06980829523060f3a96fc2b1669038e8d614f912 Mon Sep 17 00:00:00 2001
From: Joshua MacDonald <jmacd@users.noreply.github.com>
Date: Fri, 13 Dec 2019 11:55:39 -0800
Subject: [PATCH] Rename metric instrument "Handles" to "Bound Instruments"
 (open-telemetry/oteps#70)

* Add Bound Instruments OTEP

* Add status
---
 oteps/0070-metric-bound-instrument.md | 63 +++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 oteps/0070-metric-bound-instrument.md

diff --git a/oteps/0070-metric-bound-instrument.md b/oteps/0070-metric-bound-instrument.md
new file mode 100644
index 00000000000..0c730356695
--- /dev/null
+++ b/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.