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

[editorial] Use canonical URL to wiki page in metrics/api #3834

Merged
merged 2 commits into from
Jan 19, 2024
Merged

[editorial] Use canonical URL to wiki page in metrics/api #3834

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
05181c8
[editorial] Use canonical URL to wiki page in metrics/api
chalin Jan 19, 2024
223b8a3
Merge branch 'main' into chalin-im-metric-en-wiki-2024-01-18
reyang Jan 19, 2024
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
50 changes: 25 additions & 25 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,19 +132,19 @@ This API MUST accept the following parameters:
within that library or application.
* `version`: Specifies the version of the instrumentation scope if the scope
has a version (e.g. a library version). Example value: `1.0.0`.

Users can provide a `version`, but it is up to their discretion. Therefore,
this API needs to be structured to accept a `version`, but MUST NOT obligate
a user to provide one.
* [since 1.4.0] `schema_url`: Specifies the Schema URL that should be recorded
in the emitted telemetry.

Users can provide a `schema_url`, but it is up to their discretion.
Therefore, this API needs to be structured to accept a `schema_url`, but MUST
NOT obligate a user to provide one.
* [since 1.13.0] `attributes`: Specifies the instrumentation scope attributes
to associate with emitted telemetry.

Users can provide attributes to associate with the instrumentation scope, but
it is up to their discretion. Therefore, this API MUST be structured to
accept a variable number of attributes, including none.
Expand Down Expand Up @@ -308,32 +308,32 @@ pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation).
The API to construct synchronous instruments MUST accept the following parameters:

* A `name` of the Instrument.

The `name` needs to be provided by a user. If possible, the API SHOULD be
structured so a user is obligated to provide this parameter. If it is not
possible to structurally enforce this obligation, the API MUST be documented
in a way to communicate to users that this parameter is needed.

The API SHOULD be documented in a way to communicate to users that the `name`
parameter needs to conform to the [instrument name
syntax](#instrument-name-syntax). The API SHOULD NOT validate the `name`;
that is left to implementations of the API.
* A `unit` of measure.

Users can provide a `unit`, but it is up to their discretion. Therefore, this
API needs to be structured to accept a `unit`, but MUST NOT obligate a user
to provide one.

The `unit` parameter needs to support the [instrument unit
rule](#instrument-unit). Meaning, the API MUST accept a case-sensitive string
that supports ASCII character encoding and can hold at least 63 characters.
The API SHOULD NOT validate the `unit`.
* A `description` describing the Instrument in human-readable terms.

Users can provide a `description`, but it is up to their discretion.
Therefore, this API needs to be structured to accept a `description`, but
MUST NOT obligate a user to provide one.

The `description` needs to support the [instrument description
rule](#instrument-description). Meaning, the API MUST accept a string that
supports at least [BMP (Unicode Plane
Expand Down Expand Up @@ -361,32 +361,32 @@ order of callback execution is not specified.
The API to construct asynchronous instruments MUST accept the following parameters:

* A `name` of the Instrument.

The `name` needs to be provided by a user. If possible, the API SHOULD be
structured so a user is obligated to provide this parameter. If it is not
possible to structurally enforce this obligation, the API MUST be documented
in a way to communicate to users that this parameter is needed.

The API SHOULD be documented in a way to communicate to users that the `name`
parameter needs to conform to the [instrument name
syntax](#instrument-name-syntax). The API SHOULD NOT validate the `name`,
that is left to implementations of the API.
* A `unit` of measure.

Users can provide a `unit`, but it is up to their discretion. Therefore, this
API needs to be structured to accept a `unit`, but MUST NOT obligate a user
to provide one.

The `unit` parameter needs to support the [instrument unit
rule](#instrument-unit). Meaning, the API MUST accept a case-sensitive string
that supports ASCII character encoding and can hold at least 63 characters.
The API SHOULD NOT validate the `unit`.
* A `description` describing the Instrument in human-readable terms.

Users can provide a `description`, but it is up to their discretion.
Therefore, this API needs to be structured to accept a `description`, but
MUST NOT obligate a user to provide one.

The `description` needs to support the [instrument description
rule](#instrument-description). Meaning, the API MUST accept a string that
supports at least [BMP (Unicode Plane
Expand All @@ -404,7 +404,7 @@ The API to construct asynchronous instruments MUST accept the following paramete
The API SHOULD NOT validate `advisory` parameters.
* `callback` functions that report [Measurements](#measurement) of the created
instrument.

Users can provide `callback` functions, but it is up to their discretion.
Therefore, this API MUST be structured to accept a variable number of
`callback` functions, including none.
Expand Down Expand Up @@ -532,19 +532,19 @@ certain programming languages or systems, for example `null`, `undefined`).
This API MUST accept the following parameter:

* A numeric increment value.

The increment value needs to be provided by a user. If possible, this API
SHOULD be structured so a user is obligated to provide this parameter. If it
is not possible to structurally enforce this obligation, this API MUST be
documented in a way to communicate to users that this parameter is needed.

The increment value is expected to be non-negative. This API SHOULD be
documented in a way to communicate to users that this value is expected to be
non-negative. This API SHOULD NOT validate this value, that is left to
implementations of the API.
* [Attributes](../common/README.md#attribute) to associate with the increment
value.

Users can provide attributes to associate with the increment value, but it is
up to their discretion. Therefore, this API MUST be structured to accept a
variable number of attributes, including none.
Expand Down Expand Up @@ -579,7 +579,7 @@ counterPowerUsed.Add(200, new PowerConsumption { customer = "Jerry" }, ("is_gree
### Asynchronous Counter

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

Example uses for Asynchronous Counter:
Expand Down Expand Up @@ -773,13 +773,13 @@ This API MUST accept the following parameter:
structured so a user is obligated to provide this parameter. If it is not
possible to structurally enforce this obligation, this API MUST be documented
in a way to communicate to users that this parameter is needed.

The value is expected to be non-negative. This API SHOULD be documented in a
way to communicate to users that this value is expected to be non-negative.
This API SHOULD NOT validate this value, that is left to implementations of
the API.
* [Attributes](../common/README.md#attribute) to associate with the value.

Users can provide attributes to associate with the value, but it is up to
their discretion. Therefore, this API MUST be structured to accept a variable
number of attributes, including none.
Expand Down Expand Up @@ -1017,7 +1017,7 @@ class Device:
supports increments and decrements.

Note: if the value is
[monotonically](https://wikipedia.org/wiki/Monotonic_function) increasing, use
[monotonically](https://en.wikipedia.org/wiki/Monotonic_function) increasing, use
[Counter](#counter) instead.

Example uses for `UpDownCounter`:
Expand Down Expand Up @@ -1113,7 +1113,7 @@ This API MUST accept the following parameter:
possible to structurally enforce this obligation, this API MUST be documented
in a way to communicate to users that this parameter is needed.
* [Attributes](../common/README.md#attribute) to associate with the value.

Users can provide attributes to associate with the value, but it is up to
their discretion. Therefore, this API MUST be structured to accept a variable
number of attributes, including none.
Expand Down Expand Up @@ -1146,7 +1146,7 @@ processes and sum them up, so we get the total heap usage) when the instrument
is being observed.

Note: if the value is
[monotonically](https://wikipedia.org/wiki/Monotonic_function) increasing, use
[monotonically](https://en.wikipedia.org/wiki/Monotonic_function) increasing, use
[Asynchronous Counter](#asynchronous-counter) instead; if the value is
non-additive, use [Asynchronous Gauge](#asynchronous-gauge) instead.

Expand Down
Loading