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

Jump to bottom

Make multi-instrument idioms for async callbacks possible #2281

Closed
wants to merge 3 commits into from
Closed

Make multi-instrument idioms for async callbacks possible #2281

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fb23f34
make more idioms for async instruments possible
jmacd Jan 20, 2022
96d79ab
pr num
jmacd Jan 20, 2022
2a767f1
Merge branch 'main' into jmacd/morecallbackoptions
anuraaga Feb 1, 2022
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
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ release.
([#2210](https://github.com/open-telemetry/opentelemetry-specification/pull/2210))
- Use UCUM units in Metrics Semantic Conventions.
([#2199](https://github.com/open-telemetry/opentelemetry-specification/pull/2199))
- Metrics API support for multiple instruments per callback.
([#2281](https://github.com/open-telemetry/opentelemetry-specification/pull/2281))

### Logs

Expand Down
17 changes: 9 additions & 8 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,12 +253,13 @@ asynchronous:
<a name="asynchronous-instrument"></a>

* Asynchronous instruments (e.g. [Asynchronous Gauge](#asynchronous-gauge)) give
the user a way to register callback function, and the callback function will
the user a way to register one or more associated callback functions, which will
only be invoked upon collection. For example, a piece of embedded software
could use an asynchronous gauge to collect the temperature from a sensor every
15 seconds, which means the callback function will only be invoked every 15
seconds. [Measurements](#measurement) recorded by asynchronous instruments
cannot be associated with the [Context](../context/context.md).
seconds. Multiple callbacks may be associated with one instrument as a result
of duplicate instrument registration. [Measurements](#measurement) recorded by
jmacd marked this conversation as resolved.
Show resolved Hide resolved
asynchronous instruments cannot be associated with the [Context](../context/context.md).

Please note that the term _synchronous_ and _asynchronous_ have nothing to do
with the [asynchronous
Expand Down Expand Up @@ -396,12 +397,11 @@ The API MUST accept the following parameters:
rule](#instrument-unit).
* An optional `description`, following the [instrument description
rule](#instrument-description).
* A `callback` function.

The `callback` function is responsible for reporting the
[Measurement](#measurement)s. It will only be called when the Meter is being
observed. [OpenTelemetry API](../overview.md#api) authors SHOULD define whether
this callback function needs to be reentrant safe / thread safe or not.
The API MUST provide a way to associate instruments with `callback` functions
responsible for reporting the associated [Measurement](#measurement)s. The
callbacks will only be called when the Meter is being observed. [OpenTelemetry API](../overview.md#api)
authors SHOULD define whether callback functions needs to be reentrant safe / thread safe or not.

Note: Unlike [Counter.Add()](#add) which takes the increment/delta value, the
callback function reports the absolute value of the counter. To determine the
Expand All @@ -418,6 +418,7 @@ approach. Here are some examples:
* Return a list (or tuple, generator, enumerator, etc.) of `Measurement`s.
* Use an observable result argument to allow individual `Measurement`s to be
reported.
* Allow use of more than one instrument in a single callback.

User code is recommended not to provide more than one `Measurement` with the
same `attributes` in a single callback. If it happens, [OpenTelemetry
Expand Down