Merge branch 'main' into add_heroku

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.
@@ -32,6 +35,8 @@ release.
   ([#3209](https://github.com/open-telemetry/opentelemetry-specification/pull/3209))
 - Add Connect RPC specific conventions
   ([#3116](https://github.com/open-telemetry/opentelemetry-specification/pull/3116))
+- Mark the attribute naming guidelines in the specification as stable.
+  ([#3220](https://github.com/open-telemetry/opentelemetry-specification/pull/3220))
 
 ### Compatibility
 

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.

specification/common/attribute-naming.md

@@ -1,6 +1,6 @@
 # Attribute Naming
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Stable](../document-status.md)
 
 <details>
 <summary>Table of Contents</summary>

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

specification/metrics/metric-requirement-level.md

@@ -0,0 +1,40 @@
+# Metric Requirement Levels for Semantic Conventions
+
+**Status**: [Experimental](../document-status.md)
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Required](#required)
+- [Recommended](#recommended)
+- [Opt-In](#opt-in)
+
+<!-- tocstop -->
+
+</details>
+
+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.