Generate upgrade document based on deprecations #2601

.chloggen/add_back_deprecated_migrations.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: db, http, messaging
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: This enables a user to see which attributes are no longer applicable and support a migration
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [2601]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

docs/exceptions/exceptions-spans.md

@@ -35,7 +35,6 @@ 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.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-deprecation-action.md

@@ -0,0 +1,113 @@
+# Attribute deprecation actions
+
+**Status**: [Stable][DocumentStatus]
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Migrate](#migrate)
+  - [Stable Instrumentation](#stable-instrumentation)
+  - [Long-term Unstable Instrumentation](#long-term-unstable-instrumentation)
+  - [Unstable Instrumentation](#unstable-instrumentation)
+- [Rename](#rename)
+- [Remove](#remove)
+  - [Stable Instrumentation](#stable-instrumentation-1)
+  - [Long-term Unstable Instrumentation](#long-term-unstable-instrumentation-1)
+  - [Unstable Instrumentation](#unstable-instrumentation-1)
+- [Update](#update)
+- [Drop](#drop)
+
+<!-- tocstop -->
+
+</details>
+
+## Migrate
+
+The migrate action helps to facilitate a tranisition
+from a deprecated attribute to the replacement attribute.
+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 e.g. `database` via the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable.
+* User has excluded the attribute via explicit configuration
+* The instrumentation bumps its major version but will continue providing security patches for
+the previous major version for at least 6 months.
+
+The [Drop Action](#drop) can occur when the major version is bumped provided that the previous major version will/has received 6 months of security patches from the time the replacement attribute is introduced.
+
+### Long-term Unstable Instrumentation
+
+> [!NOTE]
+> Examples 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 e.g. `database/dup` via the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable.
+* User has included the attribute via explicit configuration
+
+The [Drop Action](#drop) can occur when the deployment level of the package changes.
+For instance a beta package moves to release candidate.
+
+### Unstable Instrumentation
+
+Should follow the definition of the [Drop Action](#drop) for how to proceed.
+
+## Rename
+
+The implementation is able to rename the attribute currently being emitted without needing to support the existing attribute anymore.
+
+This equivalent to adding a new attribute and performing the [Drop Action](#drop) on the old attribute.
+
+## Remove
+
+The remove action helps to facilitate the removal of a deprecated attribute.
+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 its major version but will continue providing security patches for
+the previous major version for at least 6 months.
+
+The [Drop Action](#drop) can occur when the major version is bumped provided that previous major version will/has
+received 6 months of security patches from the time that the default behaviour was changed to not emit.
+
+### Long-term Unstable Instrumentation
+
+Should stop emitting the attribute unless:
+
+* User has included the attribute via explicit configuration
+
+The [Drop Action](#drop) can occur when the deployment level of the package changes. For instance a beta package moves to release candidate.
+
+### Unstable Instrumentation
+
+Should follow the definition of the [Drop Action](#drop) for how to proceed.
+
+## Update
+
+The update action indicates that the replacement attribute is not just a rename of the existing attribute but something more.
+This could be a split of the value into multiple attributes, change in units/type of the value or something else.
+The deprecation note should provide more details of the change required and it is assumed that this action behaves just like the [Migrate action](#migrate) unless stated otherwise.
+
+## Drop
+
+The drop action is where an attribute can be removed from the implementation so that the signal will not natively emit that attribute again.
+There is no ability for a user to configure that attribute to be emitted.
+
+Under no circumstances should this attribute be added to an existing instrumentation.
+
+[DocumentStatus]:
+  https://opentelemetry.io/docs/specs/otel/document-status

docs/registry/attributes/messaging.md

@@ -196,6 +196,12 @@ Describes deprecated messaging attributes.
 | <a id="messaging-kafka-consumer-group" href="#messaging-kafka-consumer-group">`messaging.kafka.consumer.group`</a> | string | Deprecated, use `messaging.consumer.group.name` instead. | `my-group` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.consumer.group.name`. |
 | <a id="messaging-kafka-destination-partition" href="#messaging-kafka-destination-partition">`messaging.kafka.destination.partition`</a> | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Record string representation of the partition id in `messaging.destination.partition.id` attribute. |
 | <a id="messaging-kafka-message-offset" href="#messaging-kafka-message-offset">`messaging.kafka.message.offset`</a> | int | Deprecated, use `messaging.kafka.offset` instead. | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.kafka.offset`. |
+| <a id="messaging-message-payload-compressed-size-bytes" href="#messaging-message-payload-compressed-size-bytes">`messaging.message.payload_compressed_size_bytes`</a> | int | The compressed size of the message payload in bytes. [11] | `2048` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Obsoleted. |
+| <a id="messaging-message-payload-size-bytes" href="#messaging-message-payload-size-bytes">`messaging.message.payload_size_bytes`</a> | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. [12] | `2738` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.message.envelope.size`. |
 | <a id="messaging-operation" href="#messaging-operation">`messaging.operation`</a> | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.operation.type`. |
 | <a id="messaging-rocketmq-client-group" href="#messaging-rocketmq-client-group">`messaging.rocketmq.client_group`</a> | string | Deprecated, use `messaging.consumer.group.name` instead. | `myConsumerGroup` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.consumer.group.name` on the consumer spans. No replacement for producer spans. |
 | <a id="messaging-servicebus-destination-subscription-name" href="#messaging-servicebus-destination-subscription-name">`messaging.servicebus.destination.subscription_name`</a> | string | Deprecated, use `messaging.destination.subscription.name` instead. | `subscription-a` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.destination.subscription.name`. |
+
+**[11] `messaging.message.payload_compressed_size_bytes`:** Only if span represents operation on a single message.
+
+**[12] `messaging.message.payload_size_bytes`:** Only if span represents operation on a single message.

docs/registry/namespaces/android/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Android
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/app/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# App
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/aspnetcore/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Aspnetcore
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/aws/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# AWS
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/az/upgrade.md

@@ -0,0 +1,26 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Az
+
+The upgrade process helps to document what is needed to upgrade the signals to the latest version.
+
+## Event
+
+### Event: `az.resource.log`
+
+**Reason:** Replaced by `azure.resource.log`.
+
+#### Property Changes
+
+| Property | Old Value | New Value |
+| --- | --- | --- |
+| Name | az.resource.log | azure.resource.log |
+
+Note: You will need to check what other attributes/properties need to be updated.
+
+#### Attribute Changes
+
+| Old Attribute Key | Action | New Attribute Key | Summary |
+| --- | --- | --- | --- |
+| az.service_request_id | `Rename` | azure.service.request.id | Replaced by `azure.service.request.id`. |

docs/registry/namespaces/azure/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Azure
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/browser/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Browser
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/cicd/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# CICD
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/cli/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Cli
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/cloud/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Cloud
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/cloudfoundry/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# CloudFoundry
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/container/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Container
+
+No upgrade process is documented as no deprecations can be found.

docs/registry/namespaces/cpu/upgrade.md

@@ -0,0 +1,44 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# CPU
+
+The upgrade process helps to document what is needed to upgrade the signals to the latest version.
+
+## Metric
+
+### Metric: `cpu.time`
+
+**Reason:** Replaced by `system.cpu.time`.
+
+#### Property Changes
+
+| Property | Old Value | New Value |
+| --- | --- | --- |
+| Name | cpu.time | system.cpu.time |
+
+Note: You will need to check what other attributes/properties need to be updated.
+
+### Metric: `cpu.utilization`
+
+**Reason:** Replaced by `system.cpu.utilization`.
+
+#### Property Changes
+
+| Property | Old Value | New Value |
+| --- | --- | --- |
+| Name | cpu.utilization | system.cpu.utilization |
+
+Note: You will need to check what other attributes/properties need to be updated.
+
+### Metric: `cpu.frequency`
+
+**Reason:** Replaced by `system.cpu.frequency`.
+
+#### Property Changes
+
+| Property | Old Value | New Value |
+| --- | --- | --- |
+| Name | cpu.frequency | system.cpu.frequency |
+
+Note: You will need to check what other attributes/properties need to be updated.

docs/registry/namespaces/cpython/upgrade.md

@@ -0,0 +1,6 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# CPython
+
+No upgrade process is documented as no deprecations can be found.