From f46b16e442118a047cc27da24892ff048a94cd98 Mon Sep 17 00:00:00 2001 From: Diego Hurtado Date: Wed, 20 Oct 2021 13:14:21 +0200 Subject: [PATCH] Replace CAN with MAY in metric API and SDK (#2037) --- specification/metrics/api.md | 34 +++++++++++++++++----------------- specification/metrics/sdk.md | 18 +++++++++--------- 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index dbab034fe1a..a835cec53f0 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -228,10 +228,10 @@ instrument. It MUST be treated as an opaque string from the API and SDK. * It MUST support [BMP (Unicode Plane 0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane), which is basically only the first three bytes of UTF-8 (or `utf8mb3`). - [OpenTelemetry API](../overview.md#api) authors CAN decide if they want to + [OpenTelemetry API](../overview.md#api) authors MAY decide if they want to support more Unicode [Planes](https://en.wikipedia.org/wiki/Plane_(Unicode)). * It MUST support at least 1023 characters. [OpenTelemetry - API](../overview.md#api) authors CAN decide if they want to support more. + API](../overview.md#api) authors MAY decide if they want to support more. Instruments can be categorized based on whether they are synchronous or asynchronous: @@ -275,7 +275,7 @@ Example uses for `Counter`: There MUST NOT be any API for creating a `Counter` other than with a [`Meter`](#meter). This MAY be called `CreateCounter`. If strong type is -desired, [OpenTelemetry API](../overview.md#api) authors CAN decide the language +desired, [OpenTelemetry API](../overview.md#api) authors MAY decide the language idiomatic name(s), for example `CreateUInt64Counter`, `CreateDoubleCounter`, `CreateCounter`, `CreateCounter`. @@ -370,7 +370,7 @@ Example uses for Asynchronous Counter: There MUST NOT be any API for creating an Asynchronous Counter other than with a [`Meter`](#meter). This MAY be called `CreateObservableCounter`. If strong type -is desired, [OpenTelemetry API](../overview.md#api) authors CAN decide the +is desired, [OpenTelemetry API](../overview.md#api) authors MAY decide the language idiomatic name(s), for example `CreateUInt64ObservableCounter`, `CreateDoubleObservableCounter`, `CreateObservableCounter`, `CreateObservableCounter`. @@ -406,7 +406,7 @@ The callback function SHOULD NOT take indefinite amount of time. If multiple independent SDKs coexist in a running process, they MUST invoke the callback function(s) independently. -[OpenTelemetry API](../overview.md#api) authors CAN decide what is the idiomatic +[OpenTelemetry API](../overview.md#api) authors MAY decide what is the idiomatic approach. Here are some examples: * Return a list (or tuple, generator, enumerator, etc.) of `Measurement`s. @@ -415,18 +415,18 @@ approach. Here are some examples: User code is recommended not to provide more than one `Measurement` with the same `attributes` in a single callback. If it happens, [OpenTelemetry -SDK](../overview.md#sdk) authors CAN decide how to handle it in the +SDK](../overview.md#sdk) authors MAY decide how to handle it in the [SDK](./README.md#sdk). For example, during the callback invocation if two measurements `value=1, attributes={pid:4, bitness:64}` and `value=2, attributes={pid:4, bitness:64}` are reported, [OpenTelemetry -SDK](../overview.md#sdk) authors CAN decide to simply let them pass through (so +SDK](../overview.md#sdk) authors MAY decide to simply let them pass through (so the downstream consumer can handle duplication), drop the entire data, pick the last one, or something else. The API MUST treat observations from a single callback as logically taking place at a single instant, such that when recorded, observations from a single callback MUST be reported with identical timestamps. The API SHOULD provide some way to pass `state` to the callback. [OpenTelemetry -API](../overview.md#api) authors CAN decide what is the idiomatic approach (e.g. +API](../overview.md#api) authors MAY decide what is the idiomatic approach (e.g. it could be an additional parameter to the callback function, or captured by the lambda closure, or something else). @@ -495,7 +495,7 @@ Example uses for `Histogram`: There MUST NOT be any API for creating a `Histogram` other than with a [`Meter`](#meter). This MAY be called `CreateHistogram`. If strong type is -desired, [OpenTelemetry API](../overview.md#api) authors CAN decide the language +desired, [OpenTelemetry API](../overview.md#api) authors MAY decide the language idiomatic name(s), for example `CreateUInt64Histogram`, `CreateDoubleHistogram`, `CreateHistogram`, `CreateHistogram`. @@ -587,7 +587,7 @@ Example uses for Asynchronous Gauge: There MUST NOT be any API for creating an Asynchronous Gauge other than with a [`Meter`](#meter). This MAY be called `CreateObservableGauge`. If strong type is -desired, [OpenTelemetry API](../overview.md#api) authors CAN decide the language +desired, [OpenTelemetry API](../overview.md#api) authors MAY decide the language idiomatic name(s), for example `CreateUInt64ObservableGauge`, `CreateDoubleObservableGauge`, `CreateObservableGauge`, `CreateObservableGauge`. @@ -618,7 +618,7 @@ The callback function SHOULD NOT take indefinite amount of time. If multiple independent SDKs coexist in a running process, they MUST invoke the callback function(s) independently. -[OpenTelemetry API](../overview.md#api) authors CAN decide what is the idiomatic +[OpenTelemetry API](../overview.md#api) authors MAY decide what is the idiomatic approach. Here are some examples: * Return a list (or tuple, generator, enumerator, etc.) of `Measurement`s. @@ -636,7 +636,7 @@ a single instant, such that when recorded, observations from a single callback MUST be reported with identical timestamps. The API SHOULD provide some way to pass `state` to the callback. [OpenTelemetry -API](../overview.md#api) authors CAN decide what is the idiomatic approach (e.g. +API](../overview.md#api) authors MAY decide what is the idiomatic approach (e.g. it could be an additional parameter to the callback function, or captured by the lambda closure, or something else). @@ -768,7 +768,7 @@ def sell_item(color, material): There MUST NOT be any API for creating an `UpDownCounter` other than with a [`Meter`](#meter). This MAY be called `CreateUpDownCounter`. If strong type is -desired, [OpenTelemetry API](../overview.md#api) authors CAN decide the language +desired, [OpenTelemetry API](../overview.md#api) authors MAY decide the language idiomatic name(s), for example `CreateInt64UpDownCounter`, `CreateDoubleUpDownCounter`, `CreateUpDownCounter`, `CreateUpDownCounter`. @@ -858,7 +858,7 @@ Example uses for Asynchronous UpDownCounter: There MUST NOT be any API for creating an Asynchronous UpDownCounter other than with a [`Meter`](#meter). This MAY be called `CreateObservableUpDownCounter`. If -strong type is desired, [OpenTelemetry API](../overview.md#api) authors CAN +strong type is desired, [OpenTelemetry API](../overview.md#api) authors MAY decide the language idiomatic name(s), for example `CreateUInt64ObservableUpDownCounter`, `CreateDoubleObservableUpDownCounter`, `CreateObservableUpDownCounter`, @@ -895,7 +895,7 @@ The callback function SHOULD NOT take indefinite amount of time. If multiple independent SDKs coexist in a running process, they MUST invoke the callback function(s) independently. -[OpenTelemetry API](../overview.md#api) authors CAN decide what is the idiomatic +[OpenTelemetry API](../overview.md#api) authors MAY decide what is the idiomatic approach. Here are some examples: * Return a list (or tuple, generator, enumerator, etc.) of `Measurement`s. @@ -904,7 +904,7 @@ approach. Here are some examples: User code is recommended not to provide more than one `Measurement` with the same `attributes` in a single callback. If it happens, the -[SDK](./README.md#sdk) CAN decide how to handle it. For example, during the +[SDK](./README.md#sdk) MAY decide how to handle it. For example, during the callback invocation if two measurements `value=1, attributes={pid:4, bitness:64}` and `value=2, attributes={pid:4, bitness:64}` are reported, the SDK can decide to simply let them pass through (so the downstream consumer can @@ -914,7 +914,7 @@ at a single instant, such that when recorded, observations from a single callback MUST be reported with identical timestamps. The API SHOULD provide some way to pass `state` to the callback. [OpenTelemetry -API](../overview.md#api) authors CAN decide what is the idiomatic approach (e.g. +API](../overview.md#api) authors MAY decide what is the idiomatic approach (e.g. it could be an additional parameter to the callback function, or captured by the lambda closure, or something else). diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 13f3e622752..2ce7a1277d6 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -67,9 +67,9 @@ SHOULD return a valid no-op Meter for these calls, if possible. `Shutdown` SHOULD provide a way to let the caller know whether it succeeded, failed or timed out. -`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` CAN be +`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` MAY be implemented as a blocking API or an asynchronous API which notifies the caller -via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors CAN +via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide if they want to make the shutdown timeout configurable. `Shutdown` MUST be implemented at least by invoking `Shutdown` on all registered @@ -91,9 +91,9 @@ is an error condition; and if there is no error condition, it should return some **NO ERROR** status, language implementations MAY decide how to model **ERROR** and **NO ERROR**. -`ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` CAN be +`ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` MAY be implemented as a blocking API or an asynchronous API which notifies the caller -via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors CAN +via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide if they want to make the flush timeout configurable. `ForceFlush` MUST invoke `ForceFlush` on all registered @@ -555,7 +555,7 @@ to (Tn+1, Tn+2] - **ONLY** for this particular The SDK SHOULD provide a way to allow `MetricReader` to respond to [MeterProvider.ForceFlush](#forceflush) and [MeterProvider.Shutdown](#shutdown). -[OpenTelemetry SDK](../overview.md#sdk) authors CAN decide the language +[OpenTelemetry SDK](../overview.md#sdk) authors MAY decide the language idiomatic approach, for example, as `OnForceFlush` and `OnShutdown` callback functions. @@ -606,9 +606,9 @@ SHOULD return some failure for these calls, if possible. `Shutdown` SHOULD provide a way to let the caller know whether it succeeded, failed or timed out. -`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` CAN be +`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` MAY be implemented as a blocking API or an asynchronous API which notifies the caller -via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors CAN +via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide if they want to make the shutdown timeout configurable. ### Periodic exporting MetricReader @@ -750,7 +750,7 @@ invocation, but before the exporter exports the completed metrics. `ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be implemented as a blocking API or an asynchronous API which notifies the caller -via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors CAN +via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide if they want to make the flush timeout configurable. ##### Shutdown() @@ -764,7 +764,7 @@ return a Failure result. `Shutdown` SHOULD NOT block indefinitely (e.g. if it attempts to flush the data and the destination is unavailable). [OpenTelemetry SDK](../overview.md#sdk) -authors CAN decide if they want to make the shutdown timeout configurable. +authors MAY decide if they want to make the shutdown timeout configurable. ### Pull Metric Exporter