From 05181c80db430b91b591029765b28c5f884d3f51 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 18 Jan 2024 19:47:19 -0500 Subject: [PATCH] [editorial] Use canonical URL to wiki page in metrics/api --- specification/metrics/api.md | 50 ++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index b6813cbf0c1..ddf5d49b49f 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -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. @@ -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 @@ -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 @@ -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. @@ -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. @@ -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: @@ -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. @@ -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`: @@ -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. @@ -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.