Skip to content

Commit

Permalink
Use normative key words for MeterProvider's Meter API parameters (#3069)
Browse files Browse the repository at this point in the history
* Use normative key words for Meter API params

Communicate the `name` parameter is an absoluter requirement for the API
to accept as a parameter and the other parameters are truly optional by
using key words adopted by this specification and defined in BCP-14.
  • Loading branch information
MrAlias authored Jan 23, 2023
1 parent df03f5e commit 948fdf3
Showing 1 changed file with 23 additions and 6 deletions.
29 changes: 23 additions & 6 deletions specification/metrics/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ The `MeterProvider` MUST provide the following functions:

This API MUST accept the following parameters:

* `name` (required): This name SHOULD uniquely identify the [instrumentation
* `name`: This name SHOULD uniquely identify the [instrumentation
scope](../glossary.md#instrumentation-scope), such as the
[instrumentation library](../glossary.md#instrumentation-library) (e.g.
`io.opentelemetry.contrib.mongodb`), package,
Expand All @@ -140,12 +140,29 @@ This API MUST accept the following parameters:
implementation which is not even observability-related). A MeterProvider could
also return a no-op Meter here if application owners configure the SDK to
suppress telemetry produced by this library.
* `version` (optional): Specifies the version of the instrumentation scope if the scope

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.
* `version`: Specifies the version of the instrumentation scope if the scope
has a version (e.g. a library version). Example value: `1.0.0`.
* [since 1.4.0] `schema_url` (optional): Specifies the Schema URL that should be
recorded in the emitted telemetry.
* [since 1.13.0] `attributes` (optional): Specifies the instrumentation scope attributes
to associate with emitted telemetry.

Users can provide a `version`, but it is up to their discretion. Therefore,
this API needs to be structured to accept a `version`, but MUST NOT obligate
a user to provide one.
* [since 1.4.0] `schema_url`: Specifies the Schema URL that should be recorded
in the emitted telemetry.

Users can provide a `schema_url`, but it is up to their discretion.
Therefore, this API needs to be structured to accept a `schema_url`, but MUST
NOT obligate a user to provide one.
* [since 1.13.0] `attributes`: Specifies the instrumentation scope attributes
to associate with emitted telemetry.

Users can provide attributes to associate with the instrumentation scope, but
it is up to their discretion. Therefore, this API MUST be structured to
accept a variable number of attributes, including none.

Meters are identified by `name`, `version`, and `schema_url` fields. When more
than one `Meter` of the same `name`, `version`, and `schema_url` is created, it
Expand Down

0 comments on commit 948fdf3

Please sign in to comment.