From 43c995020640a7c3a0983b83994bd3fb486811e8 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 27 Apr 2021 13:40:14 -0700 Subject: [PATCH] Remove the "Func" name, use "Asynchronous" and "Observable" (#1645) * use the term Asynchronous/Observable instead of Func * call out that the ObservableCounter name has nothing to do with observer pattern * omit the return value from async instruments example code for now * Update specification/metrics/new_api.md Co-authored-by: John Watson * Update specification/metrics/new_api.md Co-authored-by: John Watson * Update specification/metrics/new_api.md Co-authored-by: John Watson * rewrap Co-authored-by: John Watson Co-authored-by: Bogdan Drutu Co-authored-by: Sergey Kanzhelev --- specification/metrics/new_api.md | 104 +++++++++++++++++-------------- 1 file changed, 56 insertions(+), 48 deletions(-) diff --git a/specification/metrics/new_api.md b/specification/metrics/new_api.md index 570b61d0bb7..8c41d360a24 100644 --- a/specification/metrics/new_api.md +++ b/specification/metrics/new_api.md @@ -31,21 +31,21 @@ Table of Contents * [Counter](#counter) * [Counter creation](#counter-creation) * [Counter operations](#counter-operations) - * [CounterFunc](#counterfunc) - * [CounterFunc creation](#counterfunc-creation) - * [CounterFunc operations](#counterfunc-operations) - * [GaugeFunc](#gaugefunc) - * [GaugeFunc creation](#gaugefunc-creation) - * [GaugeFunc operations](#gaugefunc-operations) + * [Asynchronous Counter](#asynchronous-counter) + * [Asynchronous Counter creation](#asynchronous-counter-creation) + * [Asynchronous Counter operations](#asynchronous-counter-operations) + * [Asynchronous Gauge](#asynchronous-gauge) + * [Asynchronous Gauge creation](#asynchronous-gauge-creation) + * [Asynchronous Gauge operations](#asynchronous-gauge-operations) * [Histogram](#histogram) * [Histogram creation](#histogram-creation) * [Histogram operations](#histogram-operations) * [UpDownCounter](#updowncounter) * [UpDownCounter creation](#updowncounter-creation) * [UpDownCounter operations](#updowncounter-operations) - * [UpDownCounterFunc](#updowncounter) - * [UpDownCounterFunc creation](#updowncounter-creation) - * [UpDownCounterFunc operations](#updowncounter-operations) + * [Asynchronous UpDownCounter](#asynchronous-updowncounter) + * [Asynchronous UpDownCounter creation](#asynchronous-updowncounter-creation) + * [Asynchronous UpDownCounter operations](#asynchronous-updowncounter-operations) * [Measurement](#measurement) @@ -68,7 +68,7 @@ the metrics API: | +-- Meter(name='io.opentelemetry.runtime', version='1.0.0') | | - | +-- Instrument(name='cpython.gc', attributes=['generation'], unit='kB') + | +-- Instrument(name='cpython.gc', attributes=['generation'], unit='kB') | | | +-- instruments... | @@ -324,13 +324,13 @@ counterPowerUsed.Add(13.5, new PowerConsumption { customer = "Tom" }); counterPowerUsed.Add(200, new PowerConsumption { customer = "Jerry" }, ("is_green_energy", true)); ``` -### CounterFunc +### Asynchronous Counter -`CounterFunc` is an asynchronous Instrument which reports +Asynchronous Counter is an asynchronous Instrument which reports [monotonically](https://wikipedia.org/wiki/Monotonic_function) increasing value(s) when the instrument is being observed. -Example uses for `CounterFunc`: +Example uses for Asynchronous Counter: * [CPU time](https://wikipedia.org/wiki/CPU_time), which could be reported for each thread, each process or the entire system. For example "the CPU time for @@ -338,13 +338,20 @@ Example uses for `CounterFunc`: * The number of [page faults](https://wikipedia.org/wiki/Page_fault) for each process. -#### CounterFunc creation +#### Asynchronous Counter creation -There MUST NOT be any API for creating a `CounterFunc` other than with a -[`Meter`](#meter). This MAY be called `CreateCounterFunc`. If strong type is -desired, the client can decide the language idomatic name(s), for example -`CreateUInt64CounterFunc`, `CreateDoubleCounterFunc`, -`CreateCounterFunc`, `CreateCounterFunc`. +There MUST NOT be any API for creating an Asynchronous Counter other than with a +[`Meter`](#meter). This MAY be called `CreateObservableCounter`. If strong type +is desired, the client can decide the language idomatic name(s), for example +`CreateUInt64ObservableCounter`, `CreateDoubleObservableCounter`, +`CreateObservableCounter`, `CreateObservableCounter`. + +It is highly recommended that implementations use the name `ObservableCounter` +(or any language idiomatic variation, e.g. `observable_counter`) unless there is +a strong reason not to do so. Please note that the name has nothing to do with +[asynchronous +pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation) and +[observer pattern](https://en.wikipedia.org/wiki/Observer_pattern). The API MUST accept the following parameters: @@ -405,7 +412,7 @@ def pf_callback(): (10465, ("pid", 880), ("bitness", 32)), ) -page_faults_counter_func = meter.create_counter_func(name="PF", description="process page faults", pf_callback) +meter.create_observable_counter(name="PF", description="process page faults", pf_callback) ``` ```python @@ -417,7 +424,7 @@ def pf_callback(result): result.Observe(37741921, ("pid", 4), ("bitness", 64)) result.Observe(10465, ("pid", 880), ("bitness", 32)) -page_faults_counter_func = meter.create_counter_func(name="PF", description="process page faults", pf_callback) +meter.create_observable_counter(name="PF", description="process page faults", pf_callback) ``` ```csharp @@ -432,14 +439,14 @@ interface IAtomicClock IAtomicClock clock = AtomicClock.Connect(); -var obCaesiumOscillates = meter.CreateCounterFunc("caesium_oscillates", () => clock.GetCaesiumOscillates()); +meter.CreateObservableCounter("caesium_oscillates", () => clock.GetCaesiumOscillates()); ``` -#### CounterFunc operations +#### Asynchronous Counter operations -`CounterFunc` is only intended for asynchronous scenario. The only operation is -provided by the `callback`, which is registered during the [CounterFunc -creation](#counterfunc-creation). +Asynchronous Counter is only intended for an asynchronous scenario. The only +operation is provided by the `callback`, which is registered during the +[Asynchronous Counter creation](#asynchronous-counter-creation). ### Histogram @@ -462,31 +469,32 @@ TODO TODO -### GaugeFunc +### Asynchronous Gauge -`GaugeFunc` is an asynchronous Instrument which reports non-additive value(s) -(_e.g. the room temperature - it makes no sense to report the temperature value -from multiple rooms and sum them up_) when the instrument is being observed. +Asynchronous Gauge is an asynchronous Instrument which reports non-additive +value(s) (_e.g. the room temperature - it makes no sense to report the +temperature value from multiple rooms and sum them up_) when the instrument is +being observed. Note: if the values are additive (_e.g. the process heap size - it makes sense to report the heap size from multiple processes and sum them up, so we get the -total heap usage_), use [CounterFunc](#counterfunc) or -[UpDownCounterFunc](#updowncounterfunc). +total heap usage_), use [Asynchronous Counter](#asynchronous-counter) or +[Asynchronous UpDownCounter](#asynchronous-updowncounter). -Example uses for `GaugeFunc`: +Example uses for Asynchronous Gauge: * the current room temperature * the CPU fan speed -#### GaugeFunc creation +#### Asynchronous Gauge creation TODO -#### GaugeFunc operations +#### Asynchronous Gauge operations -`GaugeFunc` is only intended for asynchronous scenario. The only operation is -provided by the `callback`, which is registered during the [GaugeFunc -creation](#gaugefunc-creation). +Asynchronous Gauge is only intended for an asynchronous scenario. The only +operation is provided by the `callback`, which is registered during the +[Asynchronous Gauge creation](#asynchronous-gauge-creation). ### UpDownCounter @@ -512,32 +520,32 @@ TODO TODO -### UpDownCounterFunc +### Asynchronous UpDownCounter -`UpDownCounterFunc` is an asynchronous Instrument which reports additive +Asynchronous UpDownCounter is an asynchronous Instrument which reports additive value(s) (_e.g. the process heap size - it makes sense to report the heap size from multiple processes and sum them up, so we get the total heap usage_) when the instrument is being observed. Note: if the value grows [monotonically](https://wikipedia.org/wiki/Monotonic_function), use -[CounterFunc](#counterfunc) instead; if the value is non-additive, use -[GaugeFunc](#gaugefunc) instead. +[Asynchronous Counter](#asynchronous-counter) instead; if the value is +non-additive, use [Asynchronous Gauge](#asynchronous-gauge) instead. -Example uses for `UpDownCounterFunc`: +Example uses for Asynchronous UpDownCounter: * the process heap size * the approximate number of items in a lock-free circular buffer -#### UpDownCounterFunc creation +#### Asynchronous UpDownCounter creation TODO -#### UpDownCounterFunc operations +#### Asynchronous UpDownCounter operations -`UpDownCounterFunc` is only intended for asynchronous scenario. The only operation is -provided by the `callback`, which is registered during the [UpDownCounterFunc -creation](#updowncounterfunc-creation). +Asynchronous UpDownCounter is only intended for an asynchronous scenario. The +only operation is provided by the `callback`, which is registered during the +[Asynchronous UpDownCounter creation](#asynchronous-updowncounter-creation). ## Measurement