chore: rename Metric Handle to Bound Instrument #638

cthulhu-bot · 2019-12-20T18:18:53Z

Which problem is this PR solving?

#634

Short description of the changes

Rename metric handler to Bound Instrument in accordance with updates to the spec

Updated references of:

handle -> instrument
getHandle -> bind
removeHandle -> unbind
getDefaultHandle -> getDefaultBound

The spec appears to make a distinction between instrument and bound instrument:
https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/api-metrics-user.md#metric-calling-conventions

But I couldn't find any delineation separating these 2 types in this repo. Hence the change of Handle to BoundInstrument and all other subtypes defined as instruments (Counter, Gauge, etc).

Further down it also present the concept of Binding as just a method on the individual instrument types: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/api-metrics-user.md#bound-instrument-api

So maybe the BoundInstruments file in opentelemetry-metrics should be named Instrument instead?

Please let me know if I missed anything in the rename or renamed something that shouldn't have been.

Thank you!

codecov-io · 2019-12-20T18:30:30Z

Codecov Report

Merging #638 into master will decrease coverage by 0.19%.
The diff coverage is 96.85%.

@@            Coverage Diff            @@
##           master     #638     +/-   ##
=========================================
- Coverage   89.88%   89.68%   -0.2%     
=========================================
  Files         213      212      -1     
  Lines       10234    10065    -169     
  Branches      933      935      +2     
=========================================
- Hits         9199     9027    -172     
- Misses       1035     1038      +3

Impacted Files	Coverage Δ
packages/opentelemetry-metrics/src/Meter.ts	`96.96% <100%> (ø)`	⬆️
...emetry-exporter-prometheus/test/prometheus.test.ts	`98.6% <100%> (-0.01%)`	⬇️
.../opentelemetry-core/test/metrics/NoopMeter.test.ts	`97.22% <100%> (ø)`	⬆️
packages/opentelemetry-metrics/test/Meter.test.ts	`100% <100%> (ø)`	⬆️
...-metrics/test/export/ConsoleMetricExporter.test.ts	`100% <100%> (ø)`	⬆️
...kages/opentelemetry-metrics/src/BoundInstrument.ts	`95.55% <100%> (ø)`
...ckages/opentelemetry-core/src/metrics/NoopMeter.ts	`80.76% <81.48%> (ø)`	⬆️
packages/opentelemetry-metrics/src/Metric.ts	`89.09% <95.65%> (ø)`	⬆️
...kages/opentelemetry-plugin-dns/test/utils/utils.ts	`33.33% <0%> (-26.67%)`	⬇️
...ages/opentelemetry-plugin-http/test/utils/utils.ts	`33.33% <0%> (-26.67%)`	⬇️
... and 27 more

packages/opentelemetry-metrics/src/Metric.ts

packages/opentelemetry-exporter-collector/src/types.ts

packages/opentelemetry-exporter-prometheus/README.md

dyladan

I was going through and commenting on these and I noticed a trend where you renamed handle => instrument which is not accurate. All metrics are instruments even if they are not bound. The renaming that should have been done was handle to boundInstrument or binding depending on context.

dyladan · 2019-12-23T13:46:05Z

getting-started/README.md

      const labelSet = meter.labels({ route: req.path });
-      const handle = requestCount.getHandle(labelSet);
-      handles.set(req.path, handle);
+      const instrument = requestCount.bind(labelSet);


Can we rename this boundInstrument and the map boundInstruments?

How about boundCounter and the map boundInstruments?

dyladan · 2019-12-23T13:46:53Z

getting-started/README.md

@@ -253,7 +253,7 @@ app.use(countAllRequests());

 Now, when we make requests to our service our meter will count all requests.

-**Note**: Creating a new `labelSet` and `handle` on every request is not ideal as creating the `labelSet` can often be an expensive operation. This is why handles are created and stored in a `Map` according to the route key.
+**Note**: Creating a new `labelSet` and `instrument` on every request is not ideal as creating the `labelSet` can often be an expensive operation. This is why instruments are created and stored in a `Map` according to the route key.


Suggested change

**Note**: Creating a new `labelSet` and `instrument` on every request is not ideal as creating the `labelSet` can often be an expensive operation. This is why instruments are created and stored in a `Map` according to the route key.

**Note**: Creating a new `labelSet` and `binding` on every request is not ideal as creating the `labelSet` can often be an expensive operation. This is why bound instruments are created and stored in a `Map` according to the route key.

dyladan · 2019-12-23T13:47:07Z

getting-started/README.md

      const labelSet = meter.labels({ route: req.path });
-      const handle = requestCount.getHandle(labelSet);
-      handles.set(req.path, handle);
+      const instrument = requestCount.bind(labelSet);


pls rename boundInstrument

boundCounter?

dyladan · 2019-12-23T13:47:23Z

getting-started/monitored-example/monitoring.js

      const labelSet = meter.labels({ route: req.path });
-      const handle = requestCount.getHandle(labelSet);
-      handles.set(req.path, handle);
+      const instrument = requestCount.bind(labelSet);


pls rename boundInstrument

boundCounter?

dyladan · 2019-12-23T13:49:16Z

packages/opentelemetry-types/src/metrics/BoundInstrument.ts

-/** A Handle for Counter Metric. */
-export interface CounterHandle {
+/** An Instrument for Counter Metric. */
+export interface CounterInstrument {


I think I would rather call this something like BoundCounter

I'll also rename the others to BoundGauge and BoundMeasure

dyladan · 2019-12-23T13:50:30Z

packages/opentelemetry-core/src/metrics/NoopMeter.ts

  }

  /**
-   * Removes the Handle from the metric, if it is present.
-   * @param labels the canonicalized LabelSet used to associate with this metric handle.
+   * Removes the Instrument from the metric, if it is present.


Binding

Suggested change

* Removes the Instrument from the metric, if it is present.

* Removes the Binding from the metric, if it is present.

dyladan · 2019-12-23T13:52:37Z

packages/opentelemetry-core/src/metrics/NoopMeter.ts

    }
  }
 }

-export class NoopCounterHandle implements CounterHandle {
+export class NoopCounterInstrument implements CounterInstrument {


I think we need to call this something like NoopBoundCounter

dyladan · 2019-12-23T13:53:27Z

packages/opentelemetry-core/src/metrics/NoopMeter.ts

@@ -165,13 +171,17 @@ export class NoopMeasureHandle implements MeasureHandle {
  }
 }

-export const NOOP_GAUGE_HANDLE = new NoopGaugeHandle();
-export const NOOP_GAUGE_METRIC = new NoopGaugeMetric(NOOP_GAUGE_HANDLE);
+export const NOOP_GAUGE_INSTRUMENT = new NoopGaugeInstrument();


I think this needs to be named like NOOP_BOUND_GAUGE

dyladan · 2019-12-23T13:53:47Z

packages/opentelemetry-exporter-prometheus/test/prometheus.test.ts


-      const handle = counter.getHandle(meter.labels({ key1: 'labelValue1' }));
-      handle.add(10);
+      const instrument = counter.bind(meter.labels({ key1: 'labelValue1' }));


rename boundInstrument

cthulhu-bot · 2019-12-23T19:26:02Z

I was going through and commenting on these and I noticed a trend where you renamed handle => instrument which is not accurate. All metrics are instruments even if they are not bound. The renaming that should have been done was handle to boundInstrument or binding depending on context.

Ok good this was my main question that you answered, because I didn't understand the difference between instrument and boundInstrument just from reading the spec.

dyladan · 2019-12-23T20:04:39Z

@cthulhu-bot please do not change history on your branch by doing force push until the code review is complete. It makes it hard to track history.

cthulhu-bot · 2019-12-23T20:05:39Z

@cthulhu-bot please do not change history on your branch by doing force push until the code review is complete. It makes it hard to track history.

Sorry i'm used to amending commits and force pushing

mayurkale22

lgtm

packages/opentelemetry-core/src/metrics/NoopMeter.ts

packages/opentelemetry-exporter-prometheus/README.md

packages/opentelemetry-metrics/src/BoundInstrument.ts

* chore: fix renames in metrics test * chore: fix formatting * chore: rename BaseInstrument to BaseBoundInstrument

cthulhu-bot · 2019-12-27T04:11:50Z

Last force push was just to squash everything down and rebase on top of the master branch, should be good to go

dyladan · 2019-12-27T13:57:40Z

@cthulhu-bot i'd like to get more @open-telemetry/javascript-approvers to look at this before moving

mayurkale22 · 2020-01-03T16:59:55Z

@open-telemetry/javascript-approvers ping, we need more reviews for this one!

dyladan · 2020-01-03T19:55:07Z

@mayurkale22 how many reviews do you think we need for this? I had hoped @bg451 would have time to look since he wrote the original implementation, but if not I think this is a relatively safe change as I'm not aware of anyone using metrics yet anyways.

mayurkale22 · 2020-01-03T20:14:51Z

Even I was waiting for @bg451's approval, but make sense to merge it now given that we already have three approvals and relatively safe change.

cthulhu-bot requested review from bg451, dyladan, markwolff, mayurkale22, obecny, OlivierAlbertini, rochdev and vmarchaud as code owners December 20, 2019 18:18

cthulhu-bot force-pushed the rename-handler-to-instrument branch from 6aaa73f to 2836cee Compare December 20, 2019 18:22

mayurkale22 added Awaiting reviewer feedback enhancement New feature or request labels Dec 20, 2019

cthulhu-bot force-pushed the rename-handler-to-instrument branch from 2836cee to 9e8d389 Compare December 20, 2019 19:22

mayurkale22 reviewed Dec 20, 2019

View reviewed changes

packages/opentelemetry-metrics/src/Metric.ts Outdated Show resolved Hide resolved

mayurkale22 reviewed Dec 20, 2019

View reviewed changes

packages/opentelemetry-metrics/src/Metric.ts Outdated Show resolved Hide resolved

cthulhu-bot force-pushed the rename-handler-to-instrument branch from 9e8d389 to 343294f Compare December 20, 2019 22:23

mayurkale22 reviewed Dec 21, 2019

View reviewed changes

packages/opentelemetry-exporter-collector/src/types.ts Outdated Show resolved Hide resolved

packages/opentelemetry-exporter-prometheus/README.md Outdated Show resolved Hide resolved

cthulhu-bot force-pushed the rename-handler-to-instrument branch 3 times, most recently from 8ba8768 to df15b31 Compare December 22, 2019 19:18

dyladan requested changes Dec 23, 2019

View reviewed changes

cthulhu-bot force-pushed the rename-handler-to-instrument branch from df15b31 to 98e9891 Compare December 23, 2019 19:57

mayurkale22 approved these changes Dec 23, 2019

View reviewed changes

dyladan reviewed Dec 24, 2019

View reviewed changes

dyladan approved these changes Dec 26, 2019

View reviewed changes

dyladan added this to the Alpha v0.4 milestone Dec 26, 2019

chore: rename Metric Handle to Bound Instrument (open-telemetry#634)

bbde5ce

* chore: fix renames in metrics test * chore: fix formatting * chore: rename BaseInstrument to BaseBoundInstrument

cthulhu-bot force-pushed the rename-handler-to-instrument branch from 22e047d to bbde5ce Compare December 26, 2019 20:24

mayurkale22 added Merge:LGTM This PR is ready to be merged by a Maintainer (has enough valid approvals, successful build, etc.) and removed Awaiting reviewer feedback labels Jan 2, 2020

mayurkale22 modified the milestones: Alpha v0.4, Alpha v0.3.2 Jan 2, 2020

mayurkale22 mentioned this pull request Jan 2, 2020

chore: 0.3.2 (patch) release proposal #659

Merged

vmarchaud approved these changes Jan 3, 2020

View reviewed changes

Merge branch 'master' into rename-handler-to-instrument

f0ec667

mayurkale22 merged commit 6f0084f into open-telemetry:master Jan 3, 2020

mayurkale22 mentioned this pull request Jan 3, 2020

Rename metric handle to bound instrument #634

Closed

pichlermarc pushed a commit to dynatrace-oss-contrib/opentelemetry-js that referenced this pull request Dec 15, 2023

chore: add all instrumentations to README (open-telemetry#638)

c7b32e8

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: rename Metric Handle to Bound Instrument #638

chore: rename Metric Handle to Bound Instrument #638

cthulhu-bot commented Dec 20, 2019 •

edited

Loading

codecov-io commented Dec 20, 2019 •

edited

Loading

dyladan left a comment

dyladan Dec 23, 2019

cthulhu-bot Dec 23, 2019

dyladan Dec 23, 2019

dyladan Dec 23, 2019

cthulhu-bot Dec 23, 2019

dyladan Dec 23, 2019

cthulhu-bot Dec 23, 2019

dyladan Dec 23, 2019

cthulhu-bot Dec 23, 2019

dyladan Dec 23, 2019

dyladan Dec 23, 2019

dyladan Dec 23, 2019

dyladan Dec 23, 2019

cthulhu-bot commented Dec 23, 2019

dyladan commented Dec 23, 2019

cthulhu-bot commented Dec 23, 2019

mayurkale22 left a comment

cthulhu-bot commented Dec 27, 2019

dyladan commented Dec 27, 2019

mayurkale22 commented Jan 3, 2020

dyladan commented Jan 3, 2020

mayurkale22 commented Jan 3, 2020

	Note: Creating a new `labelSet` and `instrument` on every request is not ideal as creating the `labelSet` can often be an expensive operation. This is why instruments are created and stored in a `Map` according to the route key.
	Note: Creating a new `labelSet` and `binding` on every request is not ideal as creating the `labelSet` can often be an expensive operation. This is why bound instruments are created and stored in a `Map` according to the route key.

	* Removes the Instrument from the metric, if it is present.
	* Removes the Binding from the metric, if it is present.

chore: rename Metric Handle to Bound Instrument #638

chore: rename Metric Handle to Bound Instrument #638

Conversation

cthulhu-bot commented Dec 20, 2019 • edited Loading

Which problem is this PR solving?

Short description of the changes

codecov-io commented Dec 20, 2019 • edited Loading

Codecov Report

dyladan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cthulhu-bot commented Dec 23, 2019

dyladan commented Dec 23, 2019

cthulhu-bot commented Dec 23, 2019

mayurkale22 left a comment

Choose a reason for hiding this comment

cthulhu-bot commented Dec 27, 2019

dyladan commented Dec 27, 2019

mayurkale22 commented Jan 3, 2020

dyladan commented Jan 3, 2020

mayurkale22 commented Jan 3, 2020

cthulhu-bot commented Dec 20, 2019 •

edited

Loading

codecov-io commented Dec 20, 2019 •

edited

Loading