Skip to content

Latest commit

 

History

History
61 lines (44 loc) · 2.52 KB

0070-metric-bound-instrument.md

File metadata and controls

61 lines (44 loc) · 2.52 KB
Raw

Rename metric instrument Handles to "Bound Instruments"

The OpenTelemetry metrics API specification refers to a concept known as "metric handles", 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 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.