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

Add clarification about async vs. sync instruments #1733

Merged
merged 10 commits into from
Jun 7, 2021
Merged

Add clarification about async vs. sync instruments #1733

Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
907d54c
add clarification about async vs. sync instruments
reyang May 28, 2021
c4a869d
add links
reyang May 28, 2021
7531a6c
improve wording
reyang May 28, 2021
757b68d
wording improvements
reyang May 28, 2021
647850e
fix broken link
reyang May 28, 2021
ea51760
adjust the wording based on the review comments
reyang Jun 1, 2021
bf34679
fix typo
reyang Jun 3, 2021
afe28f7
update the wording based on review comments
reyang Jun 3, 2021
34bf0b6
Merge branch 'main' into reyang/clarify-async-sync-instruments
carlosalberto Jun 5, 2021
68a06c3
Merge branch 'main' into reyang/clarify-async-sync-instruments
carlosalberto Jun 7, 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
63 changes: 46 additions & 17 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,9 +239,37 @@ instrument. It MUST be treated as an opaque string from the API and SDK.
* It MUST support at least 1023 characters. Individual language clients can
decide if they want to support more.

Instruments can be categorized based on whether they are synchronous or
asynchronous:

<a name="synchronous-instrument"></a>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why html tags like this? Should use markdown headers if needed.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ping @reyang

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's the same as other tags in this doc (and other spec doc such as the tracing one):

  1. we don't want them to be in the top level ToC (since they interrupt the ToC flow)
  2. we want to have an anchor

IIRC @bogdandrutu you've asked the same question before?
e.g. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule

#1578 (comment)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bogdandrutu Please fill an issue to follow up this if this is still a problem, etc. Thanks!


* Synchronous instruments (e.g. [Counter](#counter)) are meant to be invoked
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: meant to be invoked inline with application/business processing logic, within the scope of [Context](../context/context.md).

Baggage (as specififed) is available via a context. I think you can call it out below as an additional thing, but the key here is;

  • The logic is inline with the mainline processing of the application (not sheddable when under load)
  • The logic can have automagical attachment of context if desired (and all the fun contexty things).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please take another look, I believe this has been addressed.

inline with application/business processing logic. For example, an HTTP client
could use a Counter to record the number of bytes it has received.
[Measurements](#measurement) recorded by synchronous instruments can be
associated with [Baggage](../baggage/api.md) and
[Context](../context/context.md).
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

<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
only be invoked upon collection. For example, a piece of embedded software
could use an asynhronous gauge to collect the temperature from a sensor every
reyang marked this conversation as resolved.
Show resolved Hide resolved
15 seconds, which means the callback function will only be invoked every 15
seconds. [Measurements](#measurement) recorded by asynchronous instruments
cannot be associated with [Baggage](../baggage/api.md) and
[Context](../context/context.md).

Please note that the term _synchronous_ and _asynchronous_ have nothing to do
with the [asynchronous
pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation).

### Counter

`Counter` is a synchronous Instrument which supports non-negative increments.
`Counter` is a [synchronous Instrument](#synchronous-instrument) which supports
non-negative increments.

Example uses for `Counter`:

Expand Down Expand Up @@ -332,9 +360,9 @@ counterPowerUsed.Add(200, new PowerConsumption { customer = "Jerry" }, ("is_gree

### Asynchronous Counter

Asynchronous Counter is an asynchronous Instrument which reports
[monotonically](https://wikipedia.org/wiki/Monotonic_function) increasing
value(s) when the instrument is being observed.
Asynchronous Counter is an [asynchronous Instrument](#asynchronous-instrument)
which reports [monotonically](https://wikipedia.org/wiki/Monotonic_function)
increasing value(s) when the instrument is being observed.

Example uses for Asynchronous Counter:

Expand Down Expand Up @@ -456,9 +484,9 @@ operation is provided by the `callback`, which is registered during the

### Histogram

`Histogram` is a synchronous Instrument which can be used to report arbitrary
values that are likely to be statistically meaningful. It is intended for
statistics such as histograms, summaries, and percentile.
`Histogram` is a [synchronous Instrument](#synchronous-instrument) which can be
used to report arbitrary values that are likely to be statistically meaningful.
It is intended for statistics such as histograms, summaries, and percentile.

Example uses for `Histogram`:

Expand Down Expand Up @@ -540,10 +568,10 @@ httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", schem

### Asynchronous Gauge

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.
Asynchronous Gauge is an [asynchronous Instrument](#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
Expand Down Expand Up @@ -667,8 +695,8 @@ operation is provided by the `callback`, which is registered during the

### UpDownCounter

`UpDownCounter` is a synchronous Instrument which supports increments and
decrements.
`UpDownCounter` is a [synchronous Instrument](#synchronous-instrument) which
supports increments and decrements.

Note: if the value grows
[monotonically](https://wikipedia.org/wiki/Monotonic_function), use
Expand Down Expand Up @@ -805,10 +833,11 @@ customersInStore.Add(-1, new Account { Type = "residential" });

### Asynchronous UpDownCounter

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.
Asynchronous UpDownCounter is an [asynchronous
Instrument](#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
Expand Down