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

Normatively define synchronous instrument record/add parameters #3082

Merged
merged 11 commits into from
Jan 30, 2023
Merged

Normatively define synchronous instrument record/add parameters #3082

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
09ce7e4
Normatively define sync inst record params
MrAlias Jan 5, 2023
151758d
Merge branch 'main' into metric-api-inst-params
MrAlias Jan 12, 2023
5302e86
Apply suggestions from code review
MrAlias Jan 18, 2023
caacb7a
Update specification/metrics/api.md
MrAlias Jan 18, 2023
438dec3
Merge branch 'main' into metric-api-inst-params
MrAlias Jan 18, 2023
afd24c1
Address feedback, all params required
MrAlias Jan 18, 2023
ead542c
This instead of the
MrAlias Jan 18, 2023
83bd174
Recommend no validation instead of requiring it
MrAlias Jan 19, 2023
e63b9ab
Merge branch 'main' into metric-api-inst-params
MrAlias Jan 23, 2023
94c6b19
Merge branch 'main' into metric-api-inst-params
MrAlias Jan 24, 2023
559fb94
Merge branch 'main' into metric-api-inst-params
MrAlias Jan 30, 2023
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
56 changes: 47 additions & 9 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down