diff --git a/CHANGELOG.md b/CHANGELOG.md index ac9c8edf443..d41e7caf481 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ release. ### Metrics +- Add metric requirement levels "Required", "Recommended", and "Opt-In". + ([#3237](https://github.com/open-telemetry/opentelemetry-specification/pull/3237)) + ### Logs - Rename Logs API to Logs Bridge API to prevent confusion. diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index ef7887420f7..97490ae10e3 100644 --- a/semantic_conventions/README.md +++ b/semantic_conventions/README.md @@ -15,7 +15,9 @@ i.e.: ## Writing semantic conventions Semantic conventions for the spec MUST adhere to the -[attribute naming](../specification/common/attribute-naming.md) and [requirement level](../specification/common/attribute-requirement-level.md) conventions. +[attribute naming](../specification/common/attribute-naming.md), +[attribute requirement level](../specification/common/attribute-requirement-level.md), +and [metric requirement level](../specification/metrics/metric-requirement-level.md) conventions. Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.15.1/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. diff --git a/specification/metrics/README.md b/specification/metrics/README.md index aab77dbe1bc..5389370cc33 100644 --- a/specification/metrics/README.md +++ b/specification/metrics/README.md @@ -99,6 +99,7 @@ SDK](../overview.md#sdk) concept for more information. * [Metrics API](./api.md) * [Metrics SDK](./sdk.md) * [Metrics Data Model and Protocol](./data-model.md) +* [Metrics Requirement Levels](./metric-requirement-level.md) * [Semantic Conventions](./semantic_conventions/README.md) ## References diff --git a/specification/metrics/metric-requirement-level.md b/specification/metrics/metric-requirement-level.md new file mode 100644 index 00000000000..c15c4872d08 --- /dev/null +++ b/specification/metrics/metric-requirement-level.md @@ -0,0 +1,40 @@ +# Metric Requirement Levels for Semantic Conventions + +**Status**: [Experimental](../document-status.md) + +
+Table of Contents + + + +- [Required](#required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) + + + +
+ +The following metric requirement levels are specified: + +- [Required](#required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) + +## Required + +All instrumentations MUST emit the metric. +A semantic convention defining a Required metric expects that an absolute majority of instrumentation libraries and applications are able to efficiently emit it. + +## Recommended + +Instrumentations SHOULD emit the metric by default if it's readily available and can be efficiently emitted. Instrumentations MAY offer a configuration option to disable Recommended metrics. + +Instrumentations that decide not to emit `Recommended` metrics due to performance, security, privacy, or other consideration by default, SHOULD allow for opting in to emitting them as defined for the `Opt-In` requirement level if the metrics are logically applicable. + +## Opt-In + +Instrumentations SHOULD emit the metric if and only if the user configures the instrumentation to do so. +Instrumentation that doesn't support configuration MUST NOT emit `Opt-In` metrics. + +This attribute requirement level is recommended for metrics that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled deliberately by a user making an informed decision.