diff --git a/specification/metrics/api.md b/specification/metrics/api.md index de8064d9395..57f14003709 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -339,12 +339,39 @@ pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation). The API to construct synchronous instruments MUST accept the following parameters: -* The `name` of the Instrument, following the [instrument naming - rule](#instrument-naming-rule). -* An optional `unit` of measure, following the [instrument unit - rule](#instrument-unit). -* An optional `description`, following the [instrument description - rule](#instrument-description). +* A `name` of the Instrument. + + The `name` needs to be provided by a user. If possible, the API SHOULD be + structured so a user is obligated to provide this parameter. If it is not + possible to structurally enforce this obligation, the API MUST be documented + in a way to communicate to users that this parameter is needed. + + The `name` needs to follow the [instrument naming + rule](#instrument-naming-rule). The API SHOULD be documented in a way to + communicate to users that this parameter needs to conform to the linked + syntax. The API SHOULD NOT validate the `name`, that is left to + implementations of the API. +* A `unit` of measure. + + Users can provide a `unit`, but it is up to their discretion. Therefore, this + API needs to be structured to accept a `unit`, but MUST NOT obligate a user + to provide one. + + The `unit` parameter needs to support the [instrument unit + rule](#instrument-unit). Meaning, the API MUST accept a case-sensitive string + that supports ASCII character encoding and can hold at least 63 characters. + The API SHOULD NOT validate the `unit`. +* A `description` describing the Instrument in human-readable terms. + + Users can provide a `description`, but it is up to their discretion. + Therefore, this API needs to be structured to accept a `description`, but + MUST NOT obligate a user to provide one. + + The `description` needs to support the [instrument description + rule](#instrument-description). Meaning, the API MUST accept a string that + supports at least [BMP (Unicode Plane + 0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane) + encoded characters and hold at least 1023 characters. ##### Asynchronous Instrument API @@ -355,14 +382,45 @@ order of callback execution is not specified. The API to construct asynchronous instruments MUST accept the following parameters: -* The `name` of the Instrument, following the [instrument naming - rule](#instrument-naming-rule). -* An optional `unit` of measure, following the [instrument unit - rule](#instrument-unit). -* An optional `description`, following the [instrument description - rule](#instrument-description). -* Zero or more `callback` functions, responsible for reporting - [Measurement](#measurement) values of the created instrument. +* A `name` of the Instrument. + + The `name` needs to be provided by a user. If possible, the API SHOULD be + structured so a user is obligated to provide this parameter. If it is not + possible to structurally enforce this obligation, the API MUST be documented + in a way to communicate to users that this parameter is needed. + + The `name` needs to follow the [instrument naming + rule](#instrument-naming-rule). The API SHOULD be documented in a way to + communicate to users that this parameter needs to conform to the linked + syntax. The API SHOULD NOT validate the `name`, that is left to + implementations of the API. +* A `unit` of measure. + + Users can provide a `unit`, but it is up to their discretion. Therefore, this + API needs to be structured to accept a `unit`, but MUST NOT obligate a user + to provide one. + + The `unit` parameter needs to support the [instrument unit + rule](#instrument-unit). Meaning, the API MUST accept a case-sensitive string + that supports ASCII character encoding and can hold at least 63 characters. + The API SHOULD NOT validate the `unit`. +* A `description` describing the Instrument in human-readable terms. + + Users can provide a `description`, but it is up to their discretion. + Therefore, this API needs to be structured to accept a `description`, but + MUST NOT obligate a user to provide one. + + The `description` needs to support the [instrument description + rule](#instrument-description). Meaning, the API MUST accept a string that + supports at least [BMP (Unicode Plane + 0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane) + encoded characters and hold at least 1023 characters. +* `callback` functions that report [Measurements](#measurement) of the created + instrument. + + Users can provide `callback` functions, but it is up to their discretion. + Therefore, this API MUST be structured to accept a variable number of + `callback` functions, including none. The API MUST support creation of asynchronous instruments by passing zero or more `callback` functions to be permanently registered to the