From 2f10d6a684e9d2389440553993d12d2602bddf62 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 30 Jan 2023 08:55:03 -0800 Subject: [PATCH] Normatively define synchronous instrument record/add parameters (#3082) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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. * Apply suggestions from code review Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> Co-authored-by: Robert Pająk * Update specification/metrics/api.md Co-authored-by: Robert Pająk * 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. * This instead of the Consistently use the same API identifier. * Recommend no validation instead of requiring it --------- Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> Co-authored-by: Robert Pająk --- specification/metrics/api.md | 56 ++++++++++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 9 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index d27f21aaa3e..de8064d9395 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -484,10 +484,25 @@ 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. +* 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. The [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible [attributes](../common/README.md#attribute) to be passed in as arguments. If @@ -705,10 +720,24 @@ 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 numeric value to record, which MUST be a non-negative numeric value. -* Optional [attributes](../common/README.md#attribute). +* 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. + 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. [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible [attributes](../common/README.md#attribute) to be passed in as individual @@ -939,10 +968,19 @@ 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: + +* A numeric value to add. -* The amount to be added, can be positive, negative or zero. -* Optional [attributes](../common/README.md#attribute). + 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