Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove the "Func" name, use "Asynchronous" and "Observable" #1645

Merged
merged 9 commits into from
Apr 27, 2021
Merged

Remove the "Func" name, use "Asynchronous" and "Observable" #1645

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
afbf4ed
use the term Asynchronous/Observable instead of Func
reyang Apr 26, 2021
e054c24
call out that the ObservableCounter name has nothing to do with obser…
reyang Apr 26, 2021
4b6154a
omit the return value from async instruments example code for now
reyang Apr 26, 2021
d9ea135
Update specification/metrics/new_api.md
reyang Apr 26, 2021
de72095
Update specification/metrics/new_api.md
reyang Apr 26, 2021
044a768
Update specification/metrics/new_api.md
reyang Apr 26, 2021
dc0d290
rewrap
reyang Apr 26, 2021
ffb2dff
Merge branch 'main' into reyang/func-async
bogdandrutu Apr 27, 2021
6b7b7fe
Merge branch 'main' into reyang/func-async
SergeyKanzhelev Apr 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 56 additions & 48 deletions specification/metrics/new_api.md
View file
Open in desktop
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