From dd781560d41585e02587375ec0019297c3d91947 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Fri, 27 Dec 2019 16:30:19 -0800 Subject: [PATCH] Rename handle to bound instrument (@sircelsius) (#400) * Rename metric Handle to Bound Instrument * Rename metric Handle to Bound Instrument * Rename metric Handle to Bound Instrument * chore(meter): renamed from *BoundInstrument to Bound*, renamed AcquireBoundInstrument to Bind * chore(meter): renamed Release to Unbind * Self feedback in doc.go * Rename confusing method name Co-authored-by: Marc Bramaud --- api/global/internal/meter.go | 21 ++++++++-------- api/global/internal/meter_test.go | 28 +++++++++++----------- api/metric/api_test.go | 24 +++++++++---------- api/metric/common.go | 24 +++++++++---------- api/metric/counter.go | 40 +++++++++++++++---------------- api/metric/doc.go | 15 ++++++------ api/metric/gauge.go | 40 +++++++++++++++---------------- api/metric/measure.go | 40 +++++++++++++++---------------- api/metric/noop.go | 12 +++++----- api/metric/sdkhelpers.go | 14 +++++------ example/basic/main.go | 8 +++---- internal/metric/mock.go | 12 +++++----- sdk/metric/benchmark_test.go | 22 ++++++++--------- sdk/metric/monotone_test.go | 2 +- sdk/metric/sdk.go | 14 +++++------ 15 files changed, 158 insertions(+), 158 deletions(-) diff --git a/api/global/internal/meter.go b/api/global/internal/meter.go index 65f331312ed..15ca9833a86 100644 --- a/api/global/internal/meter.go +++ b/api/global/internal/meter.go @@ -85,7 +85,7 @@ var _ metric.Meter = &meter{} var _ metric.LabelSet = &labelSet{} var _ metric.LabelSetDelegate = &labelSet{} var _ metric.InstrumentImpl = &instImpl{} -var _ metric.HandleImpl = &instHandle{} +var _ metric.BoundInstrumentImpl = &instHandle{} // Provider interface and delegation @@ -181,9 +181,9 @@ func (inst *instImpl) setDelegate(d metric.Meter) { atomic.StorePointer(&inst.delegate, unsafe.Pointer(implPtr)) } -func (inst *instImpl) AcquireHandle(labels metric.LabelSet) metric.HandleImpl { +func (inst *instImpl) Bind(labels metric.LabelSet) metric.BoundInstrumentImpl { if implPtr := (*metric.InstrumentImpl)(atomic.LoadPointer(&inst.delegate)); implPtr != nil { - return (*implPtr).AcquireHandle(labels) + return (*implPtr).Bind(labels) } return &instHandle{ inst: inst, @@ -191,16 +191,16 @@ func (inst *instImpl) AcquireHandle(labels metric.LabelSet) metric.HandleImpl { } } -func (bound *instHandle) Release() { +func (bound *instHandle) Unbind() { bound.initialize.Do(func() {}) - implPtr := (*metric.HandleImpl)(atomic.LoadPointer(&bound.delegate)) + implPtr := (*metric.BoundInstrumentImpl)(atomic.LoadPointer(&bound.delegate)) if implPtr == nil { return } - (*implPtr).Release() + (*implPtr).Unbind() } // Metric updates @@ -224,15 +224,14 @@ func (bound *instHandle) RecordOne(ctx context.Context, number core.Number) { if instPtr == nil { return } - var implPtr *metric.HandleImpl + var implPtr *metric.BoundInstrumentImpl bound.initialize.Do(func() { - - implPtr = new(metric.HandleImpl) - *implPtr = (*instPtr).AcquireHandle(bound.labels) + implPtr = new(metric.BoundInstrumentImpl) + *implPtr = (*instPtr).Bind(bound.labels) atomic.StorePointer(&bound.delegate, unsafe.Pointer(implPtr)) }) if implPtr == nil { - implPtr = (*metric.HandleImpl)(atomic.LoadPointer(&bound.delegate)) + implPtr = (*metric.BoundInstrumentImpl)(atomic.LoadPointer(&bound.delegate)) } (*implPtr).RecordOne(ctx, number) } diff --git a/api/global/internal/meter_test.go b/api/global/internal/meter_test.go index 4f65c0ec5e6..e48d5b47662 100644 --- a/api/global/internal/meter_test.go +++ b/api/global/internal/meter_test.go @@ -114,17 +114,17 @@ func TestBound(t *testing.T) { labels2 := glob.Labels(lvals2) counter := glob.NewFloat64Counter("test.counter") - boundC := counter.AcquireHandle(labels1) + boundC := counter.Bind(labels1) boundC.Add(ctx, 1) boundC.Add(ctx, 1) gauge := glob.NewFloat64Gauge("test.gauge") - boundG := gauge.AcquireHandle(labels2) + boundG := gauge.Bind(labels2) boundG.Set(ctx, 1) boundG.Set(ctx, 2) measure := glob.NewInt64Measure("test.measure") - boundM := measure.AcquireHandle(labels1) + boundM := measure.Bind(labels1) boundM.Record(ctx, 1) boundM.Record(ctx, 2) @@ -165,13 +165,13 @@ func TestBound(t *testing.T) { require.Equal(t, "test.measure", mock.MeasurementBatches[2].Measurements[0].Instrument.Name) - boundC.Release() - boundG.Release() - boundM.Release() + boundC.Unbind() + boundG.Unbind() + boundM.Unbind() } -func TestRelease(t *testing.T) { - // Tests Release with SDK never installed. +func TestUnbind(t *testing.T) { + // Tests Unbind with SDK never installed. internal.ResetForTest() glob := global.MeterProvider().Meter("test") @@ -181,17 +181,17 @@ func TestRelease(t *testing.T) { labels2 := glob.Labels(lvals2) counter := glob.NewFloat64Counter("test.counter") - boundC := counter.AcquireHandle(labels1) + boundC := counter.Bind(labels1) gauge := glob.NewFloat64Gauge("test.gauge") - boundG := gauge.AcquireHandle(labels2) + boundG := gauge.Bind(labels2) measure := glob.NewInt64Measure("test.measure") - boundM := measure.AcquireHandle(labels1) + boundM := measure.Bind(labels1) - boundC.Release() - boundG.Release() - boundM.Release() + boundC.Unbind() + boundG.Unbind() + boundM.Unbind() } func TestDefaultSDK(t *testing.T) { diff --git a/api/metric/api_test.go b/api/metric/api_test.go index 051b49c3955..2925a0a96cf 100644 --- a/api/metric/api_test.go +++ b/api/metric/api_test.go @@ -374,8 +374,8 @@ func TestCounter(t *testing.T) { ctx := context.Background() labels := meter.Labels() c.Add(ctx, 42, labels) - handle := c.AcquireHandle(labels) - handle.Add(ctx, 42) + boundInstrument := c.Bind(labels) + boundInstrument.Add(ctx, 42) meter.RecordBatch(ctx, labels, c.Measurement(42)) t.Log("Testing float counter") checkBatches(t, ctx, labels, meter, core.Float64NumberKind, c.Impl()) @@ -386,8 +386,8 @@ func TestCounter(t *testing.T) { ctx := context.Background() labels := meter.Labels() c.Add(ctx, 42, labels) - handle := c.AcquireHandle(labels) - handle.Add(ctx, 42) + boundInstrument := c.Bind(labels) + boundInstrument.Add(ctx, 42) meter.RecordBatch(ctx, labels, c.Measurement(42)) t.Log("Testing int counter") checkBatches(t, ctx, labels, meter, core.Int64NumberKind, c.Impl()) @@ -401,8 +401,8 @@ func TestGauge(t *testing.T) { ctx := context.Background() labels := meter.Labels() g.Set(ctx, 42, labels) - handle := g.AcquireHandle(labels) - handle.Set(ctx, 42) + boundInstrument := g.Bind(labels) + boundInstrument.Set(ctx, 42) meter.RecordBatch(ctx, labels, g.Measurement(42)) t.Log("Testing float gauge") checkBatches(t, ctx, labels, meter, core.Float64NumberKind, g.Impl()) @@ -413,8 +413,8 @@ func TestGauge(t *testing.T) { ctx := context.Background() labels := meter.Labels() g.Set(ctx, 42, labels) - handle := g.AcquireHandle(labels) - handle.Set(ctx, 42) + boundInstrument := g.Bind(labels) + boundInstrument.Set(ctx, 42) meter.RecordBatch(ctx, labels, g.Measurement(42)) t.Log("Testing int gauge") checkBatches(t, ctx, labels, meter, core.Int64NumberKind, g.Impl()) @@ -428,8 +428,8 @@ func TestMeasure(t *testing.T) { ctx := context.Background() labels := meter.Labels() m.Record(ctx, 42, labels) - handle := m.AcquireHandle(labels) - handle.Record(ctx, 42) + boundInstrument := m.Bind(labels) + boundInstrument.Record(ctx, 42) meter.RecordBatch(ctx, labels, m.Measurement(42)) t.Log("Testing float measure") checkBatches(t, ctx, labels, meter, core.Float64NumberKind, m.Impl()) @@ -440,8 +440,8 @@ func TestMeasure(t *testing.T) { ctx := context.Background() labels := meter.Labels() m.Record(ctx, 42, labels) - handle := m.AcquireHandle(labels) - handle.Record(ctx, 42) + boundInstrument := m.Bind(labels) + boundInstrument.Record(ctx, 42) meter.RecordBatch(ctx, labels, m.Measurement(42)) t.Log("Testing int measure") checkBatches(t, ctx, labels, meter, core.Int64NumberKind, m.Impl()) diff --git a/api/metric/common.go b/api/metric/common.go index 0534199a262..4e5be4f3bc1 100644 --- a/api/metric/common.go +++ b/api/metric/common.go @@ -24,12 +24,12 @@ type commonMetric struct { instrument InstrumentImpl } -type commonHandle struct { - handle HandleImpl +type commonBoundInstrument struct { + boundInstrument BoundInstrumentImpl } -func (m commonMetric) acquireCommonHandle(labels LabelSet) commonHandle { - return newCommonHandle(m.instrument.AcquireHandle(labels)) +func (m commonMetric) bind(labels LabelSet) commonBoundInstrument { + return newCommonBoundInstrument(m.instrument.Bind(labels)) } func (m commonMetric) float64Measurement(value float64) Measurement { @@ -40,7 +40,7 @@ func (m commonMetric) int64Measurement(value int64) Measurement { return newMeasurement(m.instrument, core.NewInt64Number(value)) } -func (m commonMetric) recordOne(ctx context.Context, number core.Number, labels LabelSet) { +func (m commonMetric) directRecord(ctx context.Context, number core.Number, labels LabelSet) { m.instrument.RecordOne(ctx, number, labels) } @@ -48,12 +48,12 @@ func (m commonMetric) Impl() InstrumentImpl { return m.instrument } -func (h commonHandle) recordOne(ctx context.Context, number core.Number) { - h.handle.RecordOne(ctx, number) +func (h commonBoundInstrument) directRecord(ctx context.Context, number core.Number) { + h.boundInstrument.RecordOne(ctx, number) } -func (h commonHandle) Release() { - h.handle.Release() +func (h commonBoundInstrument) Unbind() { + h.boundInstrument.Unbind() } func newCommonMetric(instrument InstrumentImpl) commonMetric { @@ -62,9 +62,9 @@ func newCommonMetric(instrument InstrumentImpl) commonMetric { } } -func newCommonHandle(handle HandleImpl) commonHandle { - return commonHandle{ - handle: handle, +func newCommonBoundInstrument(boundInstrument BoundInstrumentImpl) commonBoundInstrument { + return commonBoundInstrument{ + boundInstrument: boundInstrument, } } diff --git a/api/metric/counter.go b/api/metric/counter.go index 2678ba7eb6a..d4ff42bac5f 100644 --- a/api/metric/counter.go +++ b/api/metric/counter.go @@ -30,41 +30,41 @@ type Int64Counter struct { commonMetric } -// Float64CounterHandle is a handle for Float64Counter. +// BoundFloat64Counter is a bound instrument for Float64Counter. // -// It inherits the Release function from commonHandle. -type Float64CounterHandle struct { - commonHandle +// It inherits the Unbind function from commonBoundInstrument. +type BoundFloat64Counter struct { + commonBoundInstrument } -// Int64CounterHandle is a handle for Int64Counter. +// BoundInt64Counter is a boundInstrument for Int64Counter. // -// It inherits the Release function from commonHandle. -type Int64CounterHandle struct { - commonHandle +// It inherits the Unbind function from commonBoundInstrument. +type BoundInt64Counter struct { + commonBoundInstrument } -// AcquireHandle creates a handle for this counter. The labels should +// Bind creates a bound instrument for this counter. The labels should // contain the keys and values for each key specified in the counter // with the WithKeys option. // // If the labels do not contain a value for the key specified in the // counter with the WithKeys option, then the missing value will be // treated as unspecified. -func (c *Float64Counter) AcquireHandle(labels LabelSet) (h Float64CounterHandle) { - h.commonHandle = c.acquireCommonHandle(labels) +func (c *Float64Counter) Bind(labels LabelSet) (h BoundFloat64Counter) { + h.commonBoundInstrument = c.bind(labels) return } -// AcquireHandle creates a handle for this counter. The labels should +// Bind creates a bound instrument for this counter. The labels should // contain the keys and values for each key specified in the counter // with the WithKeys option. // // If the labels do not contain a value for the key specified in the // counter with the WithKeys option, then the missing value will be // treated as unspecified. -func (c *Int64Counter) AcquireHandle(labels LabelSet) (h Int64CounterHandle) { - h.commonHandle = c.acquireCommonHandle(labels) +func (c *Int64Counter) Bind(labels LabelSet) (h BoundInt64Counter) { + h.commonBoundInstrument = c.bind(labels) return } @@ -88,7 +88,7 @@ func (c *Int64Counter) Measurement(value int64) Measurement { // counter with the WithKeys option, then the missing value will be // treated as unspecified. func (c *Float64Counter) Add(ctx context.Context, value float64, labels LabelSet) { - c.recordOne(ctx, core.NewFloat64Number(value), labels) + c.directRecord(ctx, core.NewFloat64Number(value), labels) } // Add adds the value to the counter's sum. The labels should contain @@ -99,15 +99,15 @@ func (c *Float64Counter) Add(ctx context.Context, value float64, labels LabelSet // counter with the WithKeys option, then the missing value will be // treated as unspecified. func (c *Int64Counter) Add(ctx context.Context, value int64, labels LabelSet) { - c.recordOne(ctx, core.NewInt64Number(value), labels) + c.directRecord(ctx, core.NewInt64Number(value), labels) } // Add adds the value to the counter's sum. -func (h *Float64CounterHandle) Add(ctx context.Context, value float64) { - h.recordOne(ctx, core.NewFloat64Number(value)) +func (b *BoundFloat64Counter) Add(ctx context.Context, value float64) { + b.directRecord(ctx, core.NewFloat64Number(value)) } // Add adds the value to the counter's sum. -func (h *Int64CounterHandle) Add(ctx context.Context, value int64) { - h.recordOne(ctx, core.NewInt64Number(value)) +func (b *BoundInt64Counter) Add(ctx context.Context, value int64) { + b.directRecord(ctx, core.NewInt64Number(value)) } diff --git a/api/metric/doc.go b/api/metric/doc.go index 13fc99b1a94..26e5884be07 100644 --- a/api/metric/doc.go +++ b/api/metric/doc.go @@ -27,7 +27,7 @@ // The primary object that handles metrics is Meter. The // implementation of the Meter is provided by SDK. Normally, the Meter // is used directly only for the LabelSet generation, batch recording -// and the handle destruction. +// and the bound instrument destruction. // // LabelSet is a set of keys and values that are in a suitable, // optimized form to be used by Meter. @@ -60,10 +60,11 @@ // the New*Measure function - this allows reporting negative values // too. To report a new value, use the Record function. // -// All the basic kinds of instruments also support creating handles -// for a potentially more efficient reporting. The handles have the -// same function names as the instruments (so counter handle has Add, -// gauge handle has Set and measure handle has Record). Handles can be -// created with the AcquireHandle function of the respective -// instrument. When done with the handle, call Release on it. +// All the basic kinds of instruments also support creating bound +// instruments for a potentially more efficient reporting. The bound +// instruments have the same function names as the instruments (so a +// Counter bound instrument has Add, a Gauge bound instrument has Set, +// and a Measure bound instrument has Record). Bound Instruments can +// be created with the Bind function of the respective +// instrument. When done with the bound instrument, call Unbind on it. package metric // import "go.opentelemetry.io/otel/api/metric" diff --git a/api/metric/gauge.go b/api/metric/gauge.go index 36cd57117d4..f69980481c5 100644 --- a/api/metric/gauge.go +++ b/api/metric/gauge.go @@ -30,41 +30,41 @@ type Int64Gauge struct { commonMetric } -// Float64GaugeHandle is a handle for Float64Gauge. +// BoundFloat64Gauge is a bound instrument for Float64Gauge. // -// It inherits the Release function from commonHandle. -type Float64GaugeHandle struct { - commonHandle +// It inherits the Unbind function from commonBoundInstrument. +type BoundFloat64Gauge struct { + commonBoundInstrument } -// Int64GaugeHandle is a handle for Int64Gauge. +// BoundInt64Gauge is a bound instrument for Int64Gauge. // -// It inherits the Release function from commonHandle. -type Int64GaugeHandle struct { - commonHandle +// It inherits the Unbind function from commonBoundInstrument. +type BoundInt64Gauge struct { + commonBoundInstrument } -// AcquireHandle creates a handle for this gauge. The labels should +// Bind creates a bound instrument for this gauge. The labels should // contain the keys and values for each key specified in the gauge // with the WithKeys option. // // If the labels do not contain a value for the key specified in the // gauge with the WithKeys option, then the missing value will be // treated as unspecified. -func (g *Float64Gauge) AcquireHandle(labels LabelSet) (h Float64GaugeHandle) { - h.commonHandle = g.acquireCommonHandle(labels) +func (g *Float64Gauge) Bind(labels LabelSet) (h BoundFloat64Gauge) { + h.commonBoundInstrument = g.bind(labels) return } -// AcquireHandle creates a handle for this gauge. The labels should +// Bind creates a bound instrument for this gauge. The labels should // contain the keys and values for each key specified in the gauge // with the WithKeys option. // // If the labels do not contain a value for the key specified in the // gauge with the WithKeys option, then the missing value will be // treated as unspecified. -func (g *Int64Gauge) AcquireHandle(labels LabelSet) (h Int64GaugeHandle) { - h.commonHandle = g.acquireCommonHandle(labels) +func (g *Int64Gauge) Bind(labels LabelSet) (h BoundInt64Gauge) { + h.commonBoundInstrument = g.bind(labels) return } @@ -88,7 +88,7 @@ func (g *Int64Gauge) Measurement(value int64) Measurement { // gauge with the WithKeys option, then the missing value will be // treated as unspecified. func (g *Float64Gauge) Set(ctx context.Context, value float64, labels LabelSet) { - g.recordOne(ctx, core.NewFloat64Number(value), labels) + g.directRecord(ctx, core.NewFloat64Number(value), labels) } // Set assigns the passed value to the value of the gauge. The labels @@ -99,15 +99,15 @@ func (g *Float64Gauge) Set(ctx context.Context, value float64, labels LabelSet) // gauge with the WithKeys option, then the missing value will be // treated as unspecified. func (g *Int64Gauge) Set(ctx context.Context, value int64, labels LabelSet) { - g.recordOne(ctx, core.NewInt64Number(value), labels) + g.directRecord(ctx, core.NewInt64Number(value), labels) } // Set assigns the passed value to the value of the gauge. -func (h *Float64GaugeHandle) Set(ctx context.Context, value float64) { - h.recordOne(ctx, core.NewFloat64Number(value)) +func (b *BoundFloat64Gauge) Set(ctx context.Context, value float64) { + b.directRecord(ctx, core.NewFloat64Number(value)) } // Set assigns the passed value to the value of the gauge. -func (h *Int64GaugeHandle) Set(ctx context.Context, value int64) { - h.recordOne(ctx, core.NewInt64Number(value)) +func (b *BoundInt64Gauge) Set(ctx context.Context, value int64) { + b.directRecord(ctx, core.NewInt64Number(value)) } diff --git a/api/metric/measure.go b/api/metric/measure.go index 01f7f1eeac5..b82687f89c2 100644 --- a/api/metric/measure.go +++ b/api/metric/measure.go @@ -30,41 +30,41 @@ type Int64Measure struct { commonMetric } -// Float64MeasureHandle is a handle for Float64Measure. +// BoundFloat64Measure is a bound instrument for Float64Measure. // -// It inherits the Release function from commonHandle. -type Float64MeasureHandle struct { - commonHandle +// It inherits the Unbind function from commonBoundInstrument. +type BoundFloat64Measure struct { + commonBoundInstrument } -// Int64MeasureHandle is a handle for Int64Measure. +// BoundInt64Measure is a bound instrument for Int64Measure. // -// It inherits the Release function from commonHandle. -type Int64MeasureHandle struct { - commonHandle +// It inherits the Unbind function from commonBoundInstrument. +type BoundInt64Measure struct { + commonBoundInstrument } -// AcquireHandle creates a handle for this measure. The labels should +// Bind creates a bound instrument for this measure. The labels should // contain the keys and values for each key specified in the measure // with the WithKeys option. // // If the labels do not contain a value for the key specified in the // measure with the WithKeys option, then the missing value will be // treated as unspecified. -func (c *Float64Measure) AcquireHandle(labels LabelSet) (h Float64MeasureHandle) { - h.commonHandle = c.acquireCommonHandle(labels) +func (c *Float64Measure) Bind(labels LabelSet) (h BoundFloat64Measure) { + h.commonBoundInstrument = c.bind(labels) return } -// AcquireHandle creates a handle for this measure. The labels should +// Bind creates a bound instrument for this measure. The labels should // contain the keys and values for each key specified in the measure // with the WithKeys option. // // If the labels do not contain a value for the key specified in the // measure with the WithKeys option, then the missing value will be // treated as unspecified. -func (c *Int64Measure) AcquireHandle(labels LabelSet) (h Int64MeasureHandle) { - h.commonHandle = c.acquireCommonHandle(labels) +func (c *Int64Measure) Bind(labels LabelSet) (h BoundInt64Measure) { + h.commonBoundInstrument = c.bind(labels) return } @@ -88,7 +88,7 @@ func (c *Int64Measure) Measurement(value int64) Measurement { // measure with the WithKeys option, then the missing value will be // treated as unspecified. func (c *Float64Measure) Record(ctx context.Context, value float64, labels LabelSet) { - c.recordOne(ctx, core.NewFloat64Number(value), labels) + c.directRecord(ctx, core.NewFloat64Number(value), labels) } // Record adds a new value to the list of measure's records. The @@ -99,15 +99,15 @@ func (c *Float64Measure) Record(ctx context.Context, value float64, labels Label // measure with the WithKeys option, then the missing value will be // treated as unspecified. func (c *Int64Measure) Record(ctx context.Context, value int64, labels LabelSet) { - c.recordOne(ctx, core.NewInt64Number(value), labels) + c.directRecord(ctx, core.NewInt64Number(value), labels) } // Record adds a new value to the list of measure's records. -func (h *Float64MeasureHandle) Record(ctx context.Context, value float64) { - h.recordOne(ctx, core.NewFloat64Number(value)) +func (b *BoundFloat64Measure) Record(ctx context.Context, value float64) { + b.directRecord(ctx, core.NewFloat64Number(value)) } // Record adds a new value to the list of measure's records. -func (h *Int64MeasureHandle) Record(ctx context.Context, value int64) { - h.recordOne(ctx, core.NewInt64Number(value)) +func (b *BoundInt64Measure) Record(ctx context.Context, value int64) { + b.directRecord(ctx, core.NewInt64Number(value)) } diff --git a/api/metric/noop.go b/api/metric/noop.go index 770837bb390..66cdd6e1f5d 100644 --- a/api/metric/noop.go +++ b/api/metric/noop.go @@ -8,28 +8,28 @@ import ( type NoopProvider struct{} type NoopMeter struct{} -type noopHandle struct{} +type noopBoundInstrument struct{} type noopLabelSet struct{} type noopInstrument struct{} var _ Provider = NoopProvider{} var _ Meter = NoopMeter{} var _ InstrumentImpl = noopInstrument{} -var _ HandleImpl = noopHandle{} +var _ BoundInstrumentImpl = noopBoundInstrument{} var _ LabelSet = noopLabelSet{} func (NoopProvider) Meter(name string) Meter { return NoopMeter{} } -func (noopHandle) RecordOne(context.Context, core.Number) { +func (noopBoundInstrument) RecordOne(context.Context, core.Number) { } -func (noopHandle) Release() { +func (noopBoundInstrument) Unbind() { } -func (noopInstrument) AcquireHandle(LabelSet) HandleImpl { - return noopHandle{} +func (noopInstrument) Bind(LabelSet) BoundInstrumentImpl { + return noopBoundInstrument{} } func (noopInstrument) RecordOne(context.Context, core.Number, LabelSet) { diff --git a/api/metric/sdkhelpers.go b/api/metric/sdkhelpers.go index 49f615c6288..882b627224b 100644 --- a/api/metric/sdkhelpers.go +++ b/api/metric/sdkhelpers.go @@ -32,23 +32,23 @@ type LabelSetDelegate interface { // InstrumentImpl is the implementation-level interface Set/Add/Record // individual metrics without precomputed labels. type InstrumentImpl interface { - // AcquireHandle creates a Handle to record metrics with + // Bind creates a Bound Instrument to record metrics with // precomputed labels. - AcquireHandle(labels LabelSet) HandleImpl + Bind(labels LabelSet) BoundInstrumentImpl // RecordOne allows the SDK to observe a single metric event. RecordOne(ctx context.Context, number core.Number, labels LabelSet) } -// HandleImpl is the implementation-level interface to Set/Add/Record +// BoundInstrumentImpl is the implementation-level interface to Set/Add/Record // individual metrics with precomputed labels. -type HandleImpl interface { +type BoundInstrumentImpl interface { // RecordOne allows the SDK to observe a single metric event. RecordOne(ctx context.Context, number core.Number) - // Release frees the resources associated with this handle. It - // does not affect the metric this handle was created through. - Release() + // Unbind frees the resources associated with this bound instrument. It + // does not affect the metric this bound instrument was created through. + Unbind() } // WrapInt64CounterInstrument wraps the instrument in the type-safe diff --git a/example/basic/main.go b/example/basic/main.go index 7950e8026fe..0a69cdfa6f8 100644 --- a/example/basic/main.go +++ b/example/basic/main.go @@ -99,11 +99,11 @@ func main() { commonLabels := meter.Labels(lemonsKey.Int(10), key.String("A", "1"), key.String("B", "2"), key.String("C", "3")) - gauge := oneMetric.AcquireHandle(commonLabels) - defer gauge.Release() + gauge := oneMetric.Bind(commonLabels) + defer gauge.Unbind() - measure := measureTwo.AcquireHandle(commonLabels) - defer measure.Release() + measure := measureTwo.Bind(commonLabels) + defer measure.Unbind() err := tracer.WithSpan(ctx, "operation", func(ctx context.Context) error { diff --git a/internal/metric/mock.go b/internal/metric/mock.go index 107ebc092b6..68b7d7582a9 100644 --- a/internal/metric/mock.go +++ b/internal/metric/mock.go @@ -64,10 +64,10 @@ type ( ) var ( - _ apimetric.InstrumentImpl = &Instrument{} - _ apimetric.HandleImpl = &Handle{} - _ apimetric.LabelSet = &LabelSet{} - _ apimetric.Meter = &Meter{} + _ apimetric.InstrumentImpl = &Instrument{} + _ apimetric.BoundInstrumentImpl = &Handle{} + _ apimetric.LabelSet = &LabelSet{} + _ apimetric.Meter = &Meter{} ) const ( @@ -76,7 +76,7 @@ const ( KindMeasure ) -func (i *Instrument) AcquireHandle(labels apimetric.LabelSet) apimetric.HandleImpl { +func (i *Instrument) Bind(labels apimetric.LabelSet) apimetric.BoundInstrumentImpl { if ld, ok := labels.(apimetric.LabelSetDelegate); ok { labels = ld.Delegate() } @@ -97,7 +97,7 @@ func (h *Handle) RecordOne(ctx context.Context, number core.Number) { doRecordBatch(ctx, h.LabelSet, h.Instrument, number) } -func (h *Handle) Release() { +func (h *Handle) Unbind() { } func doRecordBatch(ctx context.Context, labelSet *LabelSet, instrument *Instrument, number core.Number) { diff --git a/sdk/metric/benchmark_test.go b/sdk/metric/benchmark_test.go index 0ff72064695..03fa6eb5e7b 100644 --- a/sdk/metric/benchmark_test.go +++ b/sdk/metric/benchmark_test.go @@ -149,7 +149,7 @@ func BenchmarkAcquireNewHandle(b *testing.B) { b.ResetTimer() for i := 0; i < b.N; i++ { - cnt.AcquireHandle(labels[i]) + cnt.Bind(labels[i]) } } @@ -161,13 +161,13 @@ func BenchmarkAcquireExistingHandle(b *testing.B) { for i := 0; i < b.N; i++ { labels[i] = fix.sdk.Labels(labelSets[i]...) - cnt.AcquireHandle(labels[i]).Release() + cnt.Bind(labels[i]).Unbind() } b.ResetTimer() for i := 0; i < b.N; i++ { - cnt.AcquireHandle(labels[i]) + cnt.Bind(labels[i]) } } @@ -179,13 +179,13 @@ func BenchmarkAcquireReleaseExistingHandle(b *testing.B) { for i := 0; i < b.N; i++ { labels[i] = fix.sdk.Labels(labelSets[i]...) - cnt.AcquireHandle(labels[i]).Release() + cnt.Bind(labels[i]).Unbind() } b.ResetTimer() for i := 0; i < b.N; i++ { - cnt.AcquireHandle(labels[i]).Release() + cnt.Bind(labels[i]).Unbind() } } @@ -209,7 +209,7 @@ func BenchmarkInt64CounterHandleAdd(b *testing.B) { fix := newFixture(b) labs := fix.sdk.Labels(makeLabels(1)...) cnt := fix.sdk.NewInt64Counter("int64.counter") - handle := cnt.AcquireHandle(labs) + handle := cnt.Bind(labs) b.ResetTimer() @@ -236,7 +236,7 @@ func BenchmarkFloat64CounterHandleAdd(b *testing.B) { fix := newFixture(b) labs := fix.sdk.Labels(makeLabels(1)...) cnt := fix.sdk.NewFloat64Counter("float64.counter") - handle := cnt.AcquireHandle(labs) + handle := cnt.Bind(labs) b.ResetTimer() @@ -265,7 +265,7 @@ func BenchmarkInt64GaugeHandleAdd(b *testing.B) { fix := newFixture(b) labs := fix.sdk.Labels(makeLabels(1)...) gau := fix.sdk.NewInt64Gauge("int64.gauge") - handle := gau.AcquireHandle(labs) + handle := gau.Bind(labs) b.ResetTimer() @@ -292,7 +292,7 @@ func BenchmarkFloat64GaugeHandleAdd(b *testing.B) { fix := newFixture(b) labs := fix.sdk.Labels(makeLabels(1)...) gau := fix.sdk.NewFloat64Gauge("float64.gauge") - handle := gau.AcquireHandle(labs) + handle := gau.Bind(labs) b.ResetTimer() @@ -321,7 +321,7 @@ func benchmarkInt64MeasureHandleAdd(b *testing.B, name string) { fix := newFixture(b) labs := fix.sdk.Labels(makeLabels(1)...) mea := fix.sdk.NewInt64Measure(name) - handle := mea.AcquireHandle(labs) + handle := mea.Bind(labs) b.ResetTimer() @@ -348,7 +348,7 @@ func benchmarkFloat64MeasureHandleAdd(b *testing.B, name string) { fix := newFixture(b) labs := fix.sdk.Labels(makeLabels(1)...) mea := fix.sdk.NewFloat64Measure(name) - handle := mea.AcquireHandle(labs) + handle := mea.Bind(labs) b.ResetTimer() diff --git a/sdk/metric/monotone_test.go b/sdk/metric/monotone_test.go index e446953cb0a..0c3c5dadd88 100644 --- a/sdk/metric/monotone_test.go +++ b/sdk/metric/monotone_test.go @@ -76,7 +76,7 @@ func TestMonotoneGauge(t *testing.T) { gauge := sdk.NewInt64Gauge("my.gauge.name", metric.WithMonotonic(true)) - handle := gauge.AcquireHandle(sdk.Labels(key.String("a", "b"))) + handle := gauge.Bind(sdk.Labels(key.String("a", "b"))) require.Nil(t, batcher.currentTime) require.Nil(t, batcher.currentValue) diff --git a/sdk/metric/sdk.go b/sdk/metric/sdk.go index 4eeb3bcd917..30cb13e7901 100644 --- a/sdk/metric/sdk.go +++ b/sdk/metric/sdk.go @@ -148,10 +148,10 @@ type ( ) var ( - _ api.Meter = &SDK{} - _ api.LabelSet = &labels{} - _ api.InstrumentImpl = &instrument{} - _ api.HandleImpl = &record{} + _ api.Meter = &SDK{} + _ api.LabelSet = &labels{} + _ api.InstrumentImpl = &instrument{} + _ api.BoundInstrumentImpl = &record{} // hazardRecord is used as a pointer value that indicates the // value is not included in any list. (`nil` would be @@ -205,7 +205,7 @@ func (i *instrument) acquireHandle(ls *labels) *record { return rec } -func (i *instrument) AcquireHandle(ls api.LabelSet) api.HandleImpl { +func (i *instrument) Bind(ls api.LabelSet) api.BoundInstrumentImpl { labs := i.meter.labsFor(ls) return i.acquireHandle(labs) } @@ -213,7 +213,7 @@ func (i *instrument) AcquireHandle(ls api.LabelSet) api.HandleImpl { func (i *instrument) RecordOne(ctx context.Context, number core.Number, ls api.LabelSet) { ourLs := i.meter.labsFor(ls) h := i.acquireHandle(ourLs) - defer h.Release() + defer h.Unbind() h.RecordOne(ctx, number) } @@ -465,7 +465,7 @@ func (r *record) RecordOne(ctx context.Context, number core.Number) { } } -func (r *record) Release() { +func (r *record) Unbind() { for { collected := atomic.LoadInt64(&r.collectedEpoch) modified := atomic.LoadInt64(&r.modifiedEpoch)