From 6033f3765bb667390e9eea647a8ec91dcd19c5d7 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 11 Oct 2021 10:08:42 -0700 Subject: [PATCH 1/7] Clarify metrics SDK limits handling --- specification/metrics/sdk.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index b67a478517b..177d1e9e08b 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -19,6 +19,7 @@ Table of Contents * [Push Metric Exporter](#push-metric-exporter) * [Pull Metric Exporter](#pull-metric-exporter) * [Defaults and configuration](#defaults-and-configuration) +* [Limits Handling](#limits-handling) * [Compatibility requirements](#compatibility-requirements) * [Concurrency requirements](#concurrency-requirements) @@ -775,6 +776,24 @@ modeled to interact with other components in the SDK: The SDK MUST provide configuration according to the [SDK environment variables](../sdk-environment-variables.md) specification. +## Limits Handling + +The SDK MUST handle limits in a graceful way according to [Error handling in +OpenTelemetry](../error-handling.md). + +If the SDK receives float/double value from [Instruments](./api.md/#instrument), +it MUST handle all the possible values. For example, if the language runtime +supports [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754), the SDK needs to +handle NaNs and Infinites. + +It is unspecified _how_ the SDK should handle the input limits. The SDK authors +may leverage/follow the language runtime behavior for better performance, rather +than perform a check on each value coming from the API. + +It is unspecified _how_ the SDK should handle the output limits (e.g. integer +overflow). The SDK authors may rely on the language runtime behavior as long as +errors/exceptions are taken care of. + ## Compatibility requirements All the metrics components SHOULD allow new methods to be added to existing From 0e4a0b9db30329a3cdb5542fd7bb5e75e0b3cb0f Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 11 Oct 2021 13:58:10 -0700 Subject: [PATCH 2/7] fix link --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 177d1e9e08b..7d5638c25bf 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -781,7 +781,7 @@ variables](../sdk-environment-variables.md) specification. The SDK MUST handle limits in a graceful way according to [Error handling in OpenTelemetry](../error-handling.md). -If the SDK receives float/double value from [Instruments](./api.md/#instrument), +If the SDK receives float/double value from [Instruments](./api.md#instrument), it MUST handle all the possible values. For example, if the language runtime supports [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754), the SDK needs to handle NaNs and Infinites. From 65e8cc367c82b3e89270165530f27b752344bb55 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 12 Oct 2021 09:18:38 -0700 Subject: [PATCH 3/7] Update specification/metrics/sdk.md Co-authored-by: Armin Ruech --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 7d5638c25bf..b3c1355c560 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -19,7 +19,7 @@ Table of Contents * [Push Metric Exporter](#push-metric-exporter) * [Pull Metric Exporter](#pull-metric-exporter) * [Defaults and configuration](#defaults-and-configuration) -* [Limits Handling](#limits-handling) +* [Numerical Limits Handling](#numerical-limits-handling) * [Compatibility requirements](#compatibility-requirements) * [Concurrency requirements](#concurrency-requirements) From c8d297b7c54fbd437a429956a224719e8f04c025 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 12 Oct 2021 09:18:48 -0700 Subject: [PATCH 4/7] Update specification/metrics/sdk.md Co-authored-by: Armin Ruech --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index b3c1355c560..57608ac7a0b 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -776,7 +776,7 @@ modeled to interact with other components in the SDK: The SDK MUST provide configuration according to the [SDK environment variables](../sdk-environment-variables.md) specification. -## Limits Handling +## Numerical Limits Handling The SDK MUST handle limits in a graceful way according to [Error handling in OpenTelemetry](../error-handling.md). From 1404b06f7d4982cfb2d729f8e24bc4f0fafce261 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 12 Oct 2021 09:20:06 -0700 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Armin Ruech --- specification/metrics/sdk.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 57608ac7a0b..5f103d2c790 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -781,17 +781,17 @@ variables](../sdk-environment-variables.md) specification. The SDK MUST handle limits in a graceful way according to [Error handling in OpenTelemetry](../error-handling.md). -If the SDK receives float/double value from [Instruments](./api.md#instrument), +If the SDK receives float/double values from [Instruments](./api.md#instrument), it MUST handle all the possible values. For example, if the language runtime supports [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754), the SDK needs to handle NaNs and Infinites. It is unspecified _how_ the SDK should handle the input limits. The SDK authors -may leverage/follow the language runtime behavior for better performance, rather +MAY leverage/follow the language runtime behavior for better performance, rather than perform a check on each value coming from the API. It is unspecified _how_ the SDK should handle the output limits (e.g. integer -overflow). The SDK authors may rely on the language runtime behavior as long as +overflow). The SDK authors MAY rely on the language runtime behavior as long as errors/exceptions are taken care of. ## Compatibility requirements From 5da4a4a8957c349ed4032e5d68453fe87464d75d Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 12 Oct 2021 09:22:00 -0700 Subject: [PATCH 6/7] lowercase --- specification/metrics/sdk.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 5f103d2c790..a7209fe1384 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -19,7 +19,7 @@ Table of Contents * [Push Metric Exporter](#push-metric-exporter) * [Pull Metric Exporter](#pull-metric-exporter) * [Defaults and configuration](#defaults-and-configuration) -* [Numerical Limits Handling](#numerical-limits-handling) +* [Numerical limits handling](#numerical-limits-handling) * [Compatibility requirements](#compatibility-requirements) * [Concurrency requirements](#concurrency-requirements) @@ -776,10 +776,10 @@ modeled to interact with other components in the SDK: The SDK MUST provide configuration according to the [SDK environment variables](../sdk-environment-variables.md) specification. -## Numerical Limits Handling +## Numerical limits handling -The SDK MUST handle limits in a graceful way according to [Error handling in -OpenTelemetry](../error-handling.md). +The SDK MUST handle numerical limits in a graceful way according to [Error +handling in OpenTelemetry](../error-handling.md). If the SDK receives float/double values from [Instruments](./api.md#instrument), it MUST handle all the possible values. For example, if the language runtime From 71a4989c92fc8c31d3c8230732658a8acdbd7a8a Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 14 Oct 2021 19:06:23 -0700 Subject: [PATCH 7/7] update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65af17c60e9..110191f52a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ release. ([#1915](https://github.com/open-telemetry/opentelemetry-specification/pull/1915)) - Add exponential histogram to the metrics data model. ([#1935](https://github.com/open-telemetry/opentelemetry-specification/pull/1935)) +- Add clarifications on how to handle numerical limits. + ([#2007](https://github.com/open-telemetry/opentelemetry-specification/pull/2007)) ### Logs