From 09ce7e4da5646e78ce75fe75b1ffdfa374fbbe73 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Thu, 5 Jan 2023 14:16:17 -0800 Subject: [PATCH 1/6] Normatively define sync inst record params Communicate the parameters for the instrument record/add APIs using normative key words adopted by this specification and defined in BCP-14. --- specification/metrics/api.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index fb79119d1cd..36f2fed6b19 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -467,10 +467,14 @@ Increment the Counter by a fixed amount. This API SHOULD NOT return a value (it MAY return a dummy value if required by certain programming languages or systems, for example `null`, `undefined`). -Required parameters: +This API MUST accept the following parameter: -* Optional [attributes](../common/README.md#attribute). -* The increment amount, which MUST be a non-negative numeric value. +* The numeric increment value. This value is expected to be non-negative. The + API MUST NOT validate this value, that is left to the API implementation. + +Additionally, this API MAY accept the following parameters: + +* The [attributes](../common/README.md#attribute) to associate with the value. The [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible [attributes](../common/README.md#attribute) to be passed in as arguments. If @@ -688,10 +692,15 @@ Updates the statistics with the specified amount. This API SHOULD NOT return a value (it MAY return a dummy value if required by certain programming languages or systems, for example `null`, `undefined`). -Parameters: +This API MUST accept the following parameter: + +* The `Measurement` value. This value is expected to be non-negative. The API + MUST NOT validate this value, that is left to the API implementation. -* The amount of the `Measurement`, which MUST be a non-negative numeric value. -* Optional [attributes](../common/README.md#attribute). +Additionally, this API MAY accept the following parameters: + +* The [attributes](../common/README.md#attribute) to associate with the + `Measurement` value. [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible [attributes](../common/README.md#attribute) to be passed in as individual @@ -922,10 +931,13 @@ Increment or decrement the UpDownCounter by a fixed amount. This API SHOULD NOT return a value (it MAY return a dummy value if required by certain programming languages or systems, for example `null`, `undefined`). -Parameters: +This API MUST accept the following parameter: + +* The numeric value to be added. This value can be positive, negative or zero. + +Additionally, this API MAY accept the following parameters: -* The amount to be added, can be positive, negative or zero. -* Optional [attributes](../common/README.md#attribute). +* The [attributes](../common/README.md#attribute) to associate with the value. [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible [attributes](../common/README.md#attribute) to be passed in as individual From 5302e864ea1db4ecd7c80d19f4d2cbb3c1685e57 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 18 Jan 2023 08:02:13 -0800 Subject: [PATCH 2/6] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> Co-authored-by: Robert Pająk --- specification/metrics/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 72851a29f48..2a756c75949 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -472,7 +472,7 @@ This API MUST accept the following parameter: * The numeric increment value. This value is expected to be non-negative. The API MUST NOT validate this value, that is left to the API implementation. -Additionally, this API MAY accept the following parameters: +Additionally, this API MUST accept the following optional parameters: * The [attributes](../common/README.md#attribute) to associate with the value. @@ -933,7 +933,7 @@ certain programming languages or systems, for example `null`, `undefined`). This API MUST accept the following parameter: -* The numeric value to be added. This value can be positive, negative or zero. +* The value to be added. This value can be positive, negative, or zero. Additionally, this API MAY accept the following parameters: From caacb7ae13046694691f56c0768b211105621072 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 18 Jan 2023 10:07:56 -0800 Subject: [PATCH 3/6] Update specification/metrics/api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- 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 2a756c75949..256f81ceb42 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -469,7 +469,7 @@ certain programming languages or systems, for example `null`, `undefined`). This API MUST accept the following parameter: -* The numeric increment value. This value is expected to be non-negative. The +* The increment value. This value is expected to be non-negative. The API MUST NOT validate this value, that is left to the API implementation. Additionally, this API MUST accept the following optional parameters: From afd24c14eb8f1b067cbeb3d9b49d7947c69f6d7d Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 18 Jan 2023 11:01:32 -0800 Subject: [PATCH 4/6] Address feedback, all params required Feedback to these changes pointed out the original intent of the optional parameters is not to communicate the option for APIs, but for users to provide the values. Update the changes to match this intent. --- specification/metrics/api.md | 61 ++++++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 17 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 488167e6826..e607e95b2c9 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -469,12 +469,23 @@ certain programming languages or systems, for example `null`, `undefined`). This API MUST accept the following parameter: -* The increment value. This value is expected to be non-negative. The - API MUST NOT validate this value, that is left to the API implementation. - -Additionally, this API MUST accept the following optional parameters: - -* The [attributes](../common/README.md#attribute) to associate with the value. +* 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. The API MUST 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. The [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible [attributes](../common/README.md#attribute) to be passed in as arguments. If @@ -694,12 +705,22 @@ certain programming languages or systems, for example `null`, `undefined`). This API MUST accept the following parameter: -* The value to record. This value is expected to be non-negative. The API MUST - NOT validate this value, that is left to the API implementation. - -Additionally, this API MAY accept the following parameters: - -* The [attributes](../common/README.md#attribute) to associate with the value. +* A numeric value to record. + + The 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 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. + The API MUST 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. [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible [attributes](../common/README.md#attribute) to be passed in as individual @@ -932,11 +953,17 @@ certain programming languages or systems, for example `null`, `undefined`). This API MUST accept the following parameter: -* The value to be added. This value can be positive, negative, or zero. - -Additionally, this API MAY accept the following parameters: - -* The [attributes](../common/README.md#attribute) to associate with the value. +* A numeric value to add. + + The 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. +* [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. [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible [attributes](../common/README.md#attribute) to be passed in as individual From ead542c37aae7531a3775a207f5ca0e596b01bf7 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 18 Jan 2023 11:49:14 -0800 Subject: [PATCH 5/6] This instead of the Consistently use the same API identifier. --- specification/metrics/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index e607e95b2c9..10cc3d81919 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -478,7 +478,7 @@ This API MUST accept the following parameter: 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. The API MUST NOT validate this value, that is left to + non-negative. This API MUST NOT validate this value, that is left to implementations of the API. * [Attributes](../common/README.md#attribute) to associate with the increment value. @@ -714,7 +714,7 @@ This API MUST accept the following parameter: 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. - The API MUST NOT validate this value, that is left to implementations of the + This API MUST NOT validate this value, that is left to implementations of the API. * [Attributes](../common/README.md#attribute) to associate with the value. From 83bd174aaf2d0452ef035f8af98a3fd3ae86a0f6 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Thu, 19 Jan 2023 11:16:08 -0800 Subject: [PATCH 6/6] Recommend no validation instead of requiring it --- specification/metrics/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 10cc3d81919..606255f9568 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -478,7 +478,7 @@ This API MUST accept the following parameter: 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 MUST NOT validate this value, that is left to + 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. @@ -714,8 +714,8 @@ This API MUST accept the following parameter: 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 MUST NOT validate this value, that is left to implementations of the - API. + 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