[chore] Move metric requirement levels doc from spec (#831)

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
open-telemetry · Mar 22, 2024 · f94edec · f94edec
1 parent 80a2d1a
commit f94edec
Show file tree

Hide file tree

Showing 9 changed files with 56 additions and 13 deletions.
diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md
@@ -191,5 +191,5 @@ This metric is [recommended][MetricRecommended].
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRequired]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#required
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricRequired]: /docs/general/metric-requirement-level.md#required
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md
@@ -301,4 +301,4 @@ FaaS providers. This list is not exhaustive.
 * [OpenFaas Metrics](https://docs.openfaas.com/architecture/metrics/)
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/general/metric-requirement-level.md b/docs/general/metric-requirement-level.md
@@ -0,0 +1,43 @@
+# Metric Requirement Levels
+
+**Status**: [Stable][DocumentStatus]
+
+<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.
+
+[DocumentStatus]:
+  https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md
@@ -187,6 +187,6 @@ _Note: The need to report `messaging.process.messages` depends on the messaging
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md
-[MetricRequired]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#required
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#recommended
-[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#opt-in
+[MetricRequired]: /docs/general/metric-requirement-level.md#required
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
+[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in
diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md
@@ -289,4 +289,4 @@ More specific Semantic Conventions are defined for the following RPC technologie
 * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md
@@ -455,5 +455,5 @@ This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#opt-in
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md
@@ -238,4 +238,4 @@ This metric is [recommended][MetricRecommended].
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
@@ -795,8 +795,8 @@ An instrument for load average over 1 minute on Linux could be named
 an `{os}` prefix to split this metric across OSes.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
-[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
-[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/metric-requirement-level.md#opt-in
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
+[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in
 
 ### Metric: `system.linux.memory.available`
 

diff --git a/model/README.md b/model/README.md
@@ -12,7 +12,7 @@ the generated markdown output in the [docs](../docs/README.md) folder.
 Semantic conventions for the spec MUST adhere to the
 [attribute naming](../docs/general/attribute-naming.md),
 [attribute requirement level](../docs/general/attribute-requirement-level.md),
-and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md) conventions.
+and [metric requirement level](../docs/general/metric-requirement-level.md) conventions.
 
 Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.23.0/semantic-conventions/syntax.md)
 for how to write the YAML files for semantic conventions and what the YAML properties mean.