Introduce the new requirement levels

Author: thompson-tomo

docs/exceptions/exceptions-spans.md

@@ -35,7 +35,7 @@ This event describes a single exception.
 |---|---|---|---|---|---|
 | [`exception.message`](/docs/registry/attributes/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`exception.type`](/docs/registry/attributes/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`exception.escaped`](/docs/registry/attributes/exception.md) | boolean | Indicates that the exception is escaping the scope of the span. |  | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. |
+| [`exception.escaped`](/docs/registry/attributes/exception.md) | boolean | Indicates that the exception is escaping the scope of the span. |  | `Remove` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. |
 | [`exception.stacktrace`](/docs/registry/attributes/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 
 **[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise.

docs/general/attribute-requirement-level.md

@@ -112,6 +112,71 @@ particularly expensive to retrieve or might pose a security or privacy risk.
 These should therefore only be enabled explicitly by a user making an informed
 decision.
 
+## Migrate
+
+The migrate requirement level is reserved for deprecated attributes and is
+designed to help support a allowing for a phased rollout of the stable semantic conventions. 
+Under no circumstances should this attribute be added to an existing instrumentation.
+
+The type of instrumentation helps to determine how the attribute should be handled, see below.
+
+### Stable Instrumentation
+
+Should continue emitting the attribute unless:
+* User has set the domain ie `database` via the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable.
+* User has excluded the attribute via explicit configuration
+* The instrumentation bumps it's major version but will continue providing security patches for
+the previous major version for at least 6 months.
+
+Removal can occur when the major version is bumped provided previous major version will/has recieved 6 months of security patches from the time the replacement attribute is introduced.
+
+### Long-term Unstable Instrumentation
+
+> [!NOTE]
+> Example's of long term unstable instrumentation, would be the OpenTelemetry Contrib packages as 
+> their stability is following that of the signal they are implementing.
+
+Should stop emitting the attribute unless:
+* User has set the domain ie `database/dup` via the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable.
+* User has included the attribute via explicit configuration
+
+Removal can occur when the deployment level of the package changes. For instance a beta package moves to release candidate.
+
+### Unstable Instrumentation
+
+Removal can occur once the new attribute is implemented, 
+provided that the instrumentation does not fall into any of the other categories.
+Should that be the case the guidance for that category should be followed.
+
+## Remove
+
+The remove requirement level is reserved for deprecated attributes that are no longer relevant.
+Under no circumstances should this attribute be added to an existing instrumentation.
+
+The type of instrumentation helps to determine how the attribute should be handled, see below.
+
+### Stable Instrumentation
+
+Should continue emitting the attribute unless:
+* User has excluded the attribute via explicit configuration
+* The instrumentation bumps it's major version but will continue providing security patches for
+the previous major version for at least 6 months.
+
+Removal can occur when the major version is bumped provided previous major version will/has recieved 6 months of security patches from the time the replacement attribute is introduced.
+
+### Long-term Unstable Instrumentation
+
+Should stop emitting the attribute unless:
+* User has included the attribute via explicit configuration
+
+Removal can occur when the deployment level of the package changes. For instance a beta package moves to release candidate.
+
+### Unstable Instrumentation
+
+Can remove attribute at any time,
+provided that the instrumentation does not fall into any of the other categories.
+Should that be the case the guidance for that category should be followed.
+
 ## Performance suggestions
 
 Here are several examples of expensive operations to be avoided by default:

templates/registry/markdown/attribute_table.j2

@@ -8,6 +8,6 @@
 {#- Macro for creating attribute table -#}
 {% macro generate(attributes, tag_filter, attribute_registry_base_url, lineage_attributes) %}{% if (tag_filter | length == 0) %}{% set filtered_attributes = attributes %}{% else %}{% set filtered_attributes = attributes | selectattr("tag", "in", tag_filter) %}{% endif %}{% if filtered_attributes | length > 0 %}| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-{% for attribute in filtered_attributes | attribute_sort %}| {{ attrs.name_with_link(attribute, attribute_registry_base_url, lineage_attributes) }} | {{ attrs.type(attribute) }} | {{ attribute.brief | trim }}{{ notes.add({"note": attribute.note, "name": attrs.name(attribute)}) }} | {{ examples.format(attribute) | trim }} | {{ requirement.render({"level": attribute.requirement_level, "name": attrs.name(attribute)}, notes) | trim }} | {{ stability.badge(attribute.stability, attribute.deprecated, attribute.brief) | trim }} |
+{% for attribute in filtered_attributes | attribute_sort %}| {{ attrs.name_with_link(attribute, attribute_registry_base_url, lineage_attributes) }} | {{ attrs.type(attribute) }} | {{ attribute.brief | trim }}{{ notes.add({"note": attribute.note, "name": attrs.name(attribute)}) }} | {{ examples.format(attribute) | trim }} | {{ requirement.render({"level": attribute.requirement_level, "name": attrs.name(attribute), "deprecated": attribute.deprecated}, notes) | trim }} | {{ stability.badge(attribute.stability, attribute.deprecated, attribute.brief) | trim }} |
 {% endfor %}{{ notes.render() }}{{ sampling.snippet(filtered_attributes, attribute_registry_base_url, lineage_attributes) }}{{ enums.tables(filtered_attributes | selectattr("type", "mapping"), notes) }}
 {% endif %}{% endmacro %}

templates/registry/markdown/requirement.j2

@@ -1,5 +1,8 @@
 {% macro render(attr, notes) -%}
-{%- if attr.level == "recommended" %}`Recommended`
+{%- if attr.deprecated and attr.deprecated.reason == "renamed" %}`Migrate`
+{% elif attr.deprecated and attr.deprecated.reason == "obsoleted" %}`Remove`
+{% elif attr.deprecated and attr.deprecated.reason == "uncategorized" %}`Migrate`
+{% elif attr.level == "recommended" %}`Recommended`
 {% elif attr.level == "required" %}`Required`
 {% elif attr.level == "opt_in" %}`Opt-In`
 {% elif attr.level.conditionally_required %}`Conditionally Required`{{ notes.add_with_limit({"note": attr.level.conditionally_required, "name": attr.name}) }}