Skip to content

Commit

Permalink
Remove the "Func" name, use "Asynchronous" and "Observable" (#1645)
Browse files Browse the repository at this point in the history 
* 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 <jkwatson@gmail.com>

* Update specification/metrics/new_api.md

Co-authored-by: John Watson <jkwatson@gmail.com>

* Update specification/metrics/new_api.md

Co-authored-by: John Watson <jkwatson@gmail.com>

* rewrap

Co-authored-by: John Watson <jkwatson@gmail.com>
Co-authored-by: Bogdan Drutu <bogdandrutu@gmail.com>
Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>
  • Loading branch information
@reyang @jkwatson
@bogdandrutu @SergeyKanzhelev
4 people authored Apr 27, 2021
1 parent 66f4a55 commit 7ccd144
Showing 1 changed file with 56 additions and 48 deletions.
104 changes: 56 additions & 48 deletions specification/metrics/new_api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

</details>
Expand All @@ -68,7 +68,7 @@ the metrics API:
|
+-- Meter(name='io.opentelemetry.runtime', version='1.0.0')
| |
| +-- Instrument<GaugeFunc, int>(name='cpython.gc', attributes=['generation'], unit='kB')
| +-- Instrument<Asynchronous Gauge, int>(name='cpython.gc', attributes=['generation'], unit='kB')
| |
| +-- instruments...
|
Expand Down Expand Up @@ -324,27 +324,34 @@ 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
process A running in user mode, measured in seconds".
* 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<UInt64>`, `CreateCounterFunc<double>`.
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<UInt64>`, `CreateObservableCounter<double>`.

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:

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -432,14 +439,14 @@ interface IAtomicClock

IAtomicClock clock = AtomicClock.Connect();

var obCaesiumOscillates = meter.CreateCounterFunc<UInt64>("caesium_oscillates", () => clock.GetCaesiumOscillates());
meter.CreateObservableCounter<UInt64>("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

Expand All @@ -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

Expand All @@ -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

Expand Down

0 comments on commit 7ccd144

Please sign in to comment.