From 0ddbbe99a7c49d819b605c90840402d381d3b733 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 4 Jan 2023 14:20:33 -0800 Subject: [PATCH 1/6] Use normative key words for inst API params Communicate the which parameters are absolute requirement for the Synchronous and Asynchronous instrument APIs to accept and the other parameters which are truly optional by using key words adopted by this specification and defined in BCP-14. --- specification/metrics/api.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index fb79119d1cd..7454096fe56 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -324,9 +324,11 @@ The API to construct synchronous instruments MUST accept the following parameter * The `name` of the Instrument, following the [instrument naming rule](#instrument-naming-rule). -* An optional `unit` of measure, following the [instrument unit - rule](#instrument-unit). -* An optional `description`, following the [instrument description + +Additionally this API MAY accept the following parameters: + +* A `unit` of measure, following the [instrument unit rule](#instrument-unit). +* A `description`, following the [instrument description rule](#instrument-description). #### Asynchronous Instrument API @@ -340,13 +342,15 @@ The API to construct asynchronous instruments MUST accept the following paramete * The `name` of the Instrument, following the [instrument naming rule](#instrument-naming-rule). -* An optional `unit` of measure, following the [instrument unit - rule](#instrument-unit). -* An optional `description`, following the [instrument description - rule](#instrument-description). * Zero or more `callback` functions, responsible for reporting [Measurement](#measurement) values of the created instrument. +Additionally, this API MAY accept the following parameters: + +* A `unit` of measure, following the [instrument unit rule](#instrument-unit). +* A `description`, following the [instrument description + rule](#instrument-description). + The API MUST support creation of asynchronous instruments by passing zero or more `callback` functions to be permanently registered to the newly created instrument. From 0cba54cd6f1bfa8784cf39e331dca8a45501d477 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Fri, 13 Jan 2023 08:05:43 -0800 Subject: [PATCH 2/6] Update specification/metrics/api.md Co-authored-by: Joao Grassi --- specification/metrics/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 855fb2c6bb2..d802ad3c978 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -325,7 +325,7 @@ The API to construct synchronous instruments MUST accept the following parameter * The `name` of the Instrument, following the [instrument naming rule](#instrument-naming-rule). -Additionally this API MAY accept the following parameters: +Additionally, this API MAY accept the following parameters: * A `unit` of measure, following the [instrument unit rule](#instrument-unit). * A `description`, following the [instrument description From 21c91506865d6cdb2ef200193590467bab82d4e7 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 18 Jan 2023 11:46:21 -0800 Subject: [PATCH 3/6] Restructure based on PR feedback --- specification/metrics/api.md | 90 ++++++++++++++++++++++++++++-------- 1 file changed, 72 insertions(+), 18 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 16da74887cf..cae86f4ae15 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -322,14 +322,39 @@ pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation). The API to construct synchronous instruments MUST accept the following parameters: -* The `name` of the Instrument, following the [instrument naming - rule](#instrument-naming-rule). - -Additionally, this API MAY accept the following parameters: - -* A `unit` of measure, following the [instrument unit rule](#instrument-unit). -* A `description`, following the [instrument description - rule](#instrument-description). +* 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 `name` needs to following the [instrument naming + rule](#instrument-naming-rule). The API SHOULD be documented in a way to + communicate to users that this parameter needs to conform to the linked + syntax. The API MUST 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 MUST 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 + 0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane) + encoded characters and hold at least 1023 characters. ##### Asynchronous Instrument API @@ -340,16 +365,45 @@ order of callback execution is not specified. The API to construct asynchronous instruments MUST accept the following parameters: -* The `name` of the Instrument, following the [instrument naming - rule](#instrument-naming-rule). -* Zero or more `callback` functions, responsible for reporting - [Measurement](#measurement) values of the created instrument. - -Additionally, this API MAY accept the following parameters: - -* A `unit` of measure, following the [instrument unit rule](#instrument-unit). -* A `description`, following the [instrument description - rule](#instrument-description). +* 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 `name` needs to following the [instrument naming + rule](#instrument-naming-rule). The API SHOULD be documented in a way to + communicate to users that this parameter needs to conform to the linked + syntax. The API MUST 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 MUST 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 + 0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane) + encoded characters and hold at least 1023 characters. +* `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. The API MUST support creation of asynchronous instruments by passing zero or more `callback` functions to be permanently registered to the From 92748b2616c29df7505c8c86d52bdf7dcf23d582 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 18 Jan 2023 15:46:26 -0800 Subject: [PATCH 4/6] Update specification/metrics/api.md Co-authored-by: Tristan Sloughter --- specification/metrics/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index cae86f4ae15..3437e686eeb 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -329,7 +329,7 @@ The API to construct synchronous instruments MUST accept the following parameter possible to structurally enforce this obligation, the API MUST be documented in a way to communicate to users that this parameter is needed. - The `name` needs to following the [instrument naming + The `name` needs to follow the [instrument naming rule](#instrument-naming-rule). The API SHOULD be documented in a way to communicate to users that this parameter needs to conform to the linked syntax. The API MUST NOT validate the `name`, that is left to implementations From 59deb2e407844764ef26c962a87a68bd0b38065a Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 18 Jan 2023 15:46:34 -0800 Subject: [PATCH 5/6] Update specification/metrics/api.md Co-authored-by: Tristan Sloughter --- specification/metrics/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 3437e686eeb..b5ad93ff820 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -372,7 +372,7 @@ The API to construct asynchronous instruments MUST accept the following paramete possible to structurally enforce this obligation, the API MUST be documented in a way to communicate to users that this parameter is needed. - The `name` needs to following the [instrument naming + The `name` needs to follow the [instrument naming rule](#instrument-naming-rule). The API SHOULD be documented in a way to communicate to users that this parameter needs to conform to the linked syntax. The API MUST NOT validate the `name`, that is left to implementations From 4e66371861e2af7d06b8b16072c604e7edb8d237 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Thu, 19 Jan 2023 11:14:14 -0800 Subject: [PATCH 6/6] Recommend no validation instead of requiring --- specification/metrics/api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index b5ad93ff820..fd174b1389f 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -332,8 +332,8 @@ The API to construct synchronous instruments MUST accept the following parameter The `name` needs to follow the [instrument naming rule](#instrument-naming-rule). The API SHOULD be documented in a way to communicate to users that this parameter needs to conform to the linked - syntax. The API MUST NOT validate the `name`, that is left to implementations - of the API. + 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 @@ -343,7 +343,7 @@ The API to construct synchronous instruments MUST accept the following parameter 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 MUST NOT validate the `unit`. + 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. @@ -375,8 +375,8 @@ The API to construct asynchronous instruments MUST accept the following paramete The `name` needs to follow the [instrument naming rule](#instrument-naming-rule). The API SHOULD be documented in a way to communicate to users that this parameter needs to conform to the linked - syntax. The API MUST NOT validate the `name`, that is left to implementations - of the API. + 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 @@ -386,7 +386,7 @@ The API to construct asynchronous instruments MUST accept the following paramete 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 MUST NOT validate the `unit`. + 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.