diff --git a/specification/metrics/new_api.md b/specification/metrics/new_api.md index 7da89bd6a84..72a040618ae 100644 --- a/specification/metrics/new_api.md +++ b/specification/metrics/new_api.md @@ -355,13 +355,16 @@ some examples: * Return a list (or tuple, generator, enumerator, etc.) of `Measurement`s. * Use an observer argument to allow individual `Measurement`s to be reported. -A single timestamp MUST be used per invocation of the callback. Duplicates are -not allowed. If it happens, the [SDK](./README.md#sdk) can 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 handle duplication), drop the entire data, pick the last one, or -something else. +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 +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 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. Individual language client can decide what is the idomatic approach (e.g. it could be an