Deprecate error.message in favor of domain-specific attributes

.chloggen/deprecate-error-message.yaml

@@ -0,0 +1,5 @@
+change_type: breaking
+component: error, feature-flags
+note: >
+  Deprecate `error.message` in favor of using domain-specific codes such as `feature_flag.error.message`.
+issues: [3307, 3308]

docs/feature-flags/feature-flags-events.md

@@ -56,8 +56,8 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu
 | [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | Describes a class of error the operation ended with. [2] | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` |
 | [`feature_flag.result.value`](/docs/registry/attributes/feature-flag.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` [3] | any | The evaluated value of the feature flag. [4] | `#ff0000`; `true`; `3` |
 | [`feature_flag.result.variant`](/docs/registry/attributes/feature-flag.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` [5] | string | A semantic identifier for an evaluated flag value. [6] | `red`; `true`; `on` |
-| [`error.message`](/docs/registry/attributes/error.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` [7] | string | A message providing more detail about an error in human-readable form. [8] | `Unexpected input type: string`; `The user has exceeded their storage quota` |
 | [`feature_flag.context.id`](/docs/registry/attributes/feature-flag.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` |
+| [`feature_flag.error.message`](/docs/registry/attributes/feature-flag.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` [7] | string | A message providing more detail about an error that occurred during feature flag evaluation in human-readable form. [8] | `Unexpected input type: string`; `The user has exceeded their storage quota` |
 | [`feature_flag.provider.name`](/docs/registry/attributes/feature-flag.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | Identifies the feature flag provider. | `Flag Manager` |
 | [`feature_flag.result.reason`](/docs/registry/attributes/feature-flag.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` |
 | [`feature_flag.set.id`](/docs/registry/attributes/feature-flag.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` |
@@ -93,9 +93,9 @@ for referring to a value without including the value itself. This can
 provide additional context for understanding the meaning behind a value.
 For example, the variant `red` maybe be used for the value `#c05543`.
 
-**[7] `error.message`:** If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error.
+**[7] `feature_flag.error.message`:** If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error.
 
-**[8] `error.message`:** Should not simply duplicate the value of `error.type`, but should provide more context. For example, if `error.type` is `invalid_context` the `error.message` may enumerate which context keys are missing or invalid.
+**[8] `feature_flag.error.message`:** Should not simply duplicate the value of `error.type`, but should provide more context. For example, if `error.type` is `invalid_context` the `feature_flag.error.message` may enumerate which context keys are missing or invalid.
 
 ---
 

docs/registry/attributes/error.md

@@ -3,6 +3,9 @@
 
 # Error
 
+- [Error Attributes](#error-attributes)
+- [Deprecated Error Attributes](#deprecated-error-attributes)
+
 ## Error Attributes
 
 This document defines the shared attributes used to report an error.
@@ -11,16 +14,9 @@ This document defines the shared attributes used to report an error.
 
 | Key | Stability | Value Type | Description | Example Values |
 | --- | --- | --- | --- | --- |
-| <a id="error-message" href="#error-message">`error.message`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | A message providing more detail about an error in human-readable form. [1] | `Unexpected input type: string`; `The user has exceeded their storage quota` |
-| <a id="error-type" href="#error-type">`error.type`</a> | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` |
+| <a id="error-type" href="#error-type">`error.type`</a> | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` |
 
-**[1] `error.message`:** `error.message` should provide additional context and detail about an error.
-It is NOT RECOMMENDED to duplicate the value of `error.type` in `error.message`.
-It is also NOT RECOMMENDED to duplicate the value of `exception.message` in `error.message`.
-
-`error.message` is NOT RECOMMENDED for metrics or spans due to its unbounded cardinality and overlap with span status.
-
-**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
+**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
 
 When `error.type` is set to a type (e.g., an exception type), its
 canonical class name identifying the type within the artifact SHOULD be used.
@@ -47,3 +43,19 @@ it's RECOMMENDED to:
 | Value | Description | Stability |
 | --- | --- | --- |
 | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+
+## Deprecated Error Attributes
+
+This document defines deprecated attributes used to report an error.
+
+**Attributes:**
+
+| Key | Stability | Value Type | Description | Example Values |
+| --- | --- | --- | --- | --- |
+| <a id="error-message" href="#error-message">`error.message`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Use domain-specific error message attribute. For example, use `feature_flag.error.message` for feature flag errors. | string | A message providing more detail about an error in human-readable form. [2] | `Unexpected input type: string`; `The user has exceeded their storage quota` |
+
+**[2] `error.message`:** `error.message` should provide additional context and detail about an error.
+It is NOT RECOMMENDED to duplicate the value of `error.type` in `error.message`.
+It is also NOT RECOMMENDED to duplicate the value of `exception.message` in `error.message`.
+
+`error.message` is NOT RECOMMENDED for metrics or spans due to its unbounded cardinality and overlap with span status.

docs/registry/attributes/feature-flag.md

@@ -15,6 +15,7 @@ This document defines attributes for Feature Flags.
 | Key | Stability | Value Type | Description | Example Values |
 | --- | --- | --- | --- | --- |
 | <a id="feature-flag-context-id" href="#feature-flag-context-id">`feature_flag.context.id`</a> | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` |
+| <a id="feature-flag-error-message" href="#feature-flag-error-message">`feature_flag.error.message`</a> | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | string | A message providing more detail about an error that occurred during feature flag evaluation in human-readable form. | `Unexpected input type: string`; `The user has exceeded their storage quota` |
 | <a id="feature-flag-key" href="#feature-flag-key">`feature_flag.key`</a> | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | string | The lookup key of the feature flag. | `logo-color` |
 | <a id="feature-flag-provider-name" href="#feature-flag-provider-name">`feature_flag.provider.name`</a> | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | string | Identifies the feature flag provider. | `Flag Manager` |
 | <a id="feature-flag-result-reason" href="#feature-flag-result-reason">`feature_flag.result.reason`</a> | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` |
@@ -58,7 +59,7 @@ Describes deprecated feature flag attributes.
 
 | Key | Stability | Value Type | Description | Example Values |
 | --- | --- | --- | --- | --- |
-| <a id="feature-flag-evaluation-error-message" href="#feature-flag-evaluation-error-message">`feature_flag.evaluation.error.message`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `error.message`. | string | Deprecated, use `error.message` instead. | `Flag `header-color` expected type `string` but found type `number`` |
+| <a id="feature-flag-evaluation-error-message" href="#feature-flag-evaluation-error-message">`feature_flag.evaluation.error.message`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `feature_flag.error.message`. | string | Deprecated, use `feature_flag.error.message` instead. | `Flag `header-color` expected type `string` but found type `number`` |
 | <a id="feature-flag-evaluation-reason" href="#feature-flag-evaluation-reason">`feature_flag.evaluation.reason`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `feature_flag.result.reason`. | string | Deprecated, use `feature_flag.result.reason` instead. | `static`; `targeting_match`; `error`; `default` |
 | <a id="feature-flag-provider-name" href="#feature-flag-provider-name">`feature_flag.provider_name`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `feature_flag.provider.name`. | string | Deprecated, use `feature_flag.provider.name` instead. | `Flag Manager` |
 | <a id="feature-flag-variant" href="#feature-flag-variant">`feature_flag.variant`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `feature_flag.result.variant`. | string | Deprecated, use `feature_flag.result.variant` instead. | `red`; `true`; `on` |

docs/registry/attributes/rpc.md

@@ -107,7 +107,7 @@ Deprecated rpc message attributes.
 | <a id="rpc-grpc-response-metadata" href="#rpc-grpc-response-metadata">`rpc.grpc.response.metadata.<key>`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `rpc.response.metadata`. | string[] | Deprecated, use `rpc.response.metadata` instead. | `["attribute_value"]` |
 | <a id="rpc-grpc-status-code" href="#rpc-grpc-status-code">`rpc.grpc.status_code`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Use string representation of the gRPC status code on the `rpc.response.status_code` attribute. | int | Deprecated, use string representation on the `rpc.response.status_code` attribute instead. | `0`; `1`; `2` |
 | <a id="rpc-jsonrpc-error-code" href="#rpc-jsonrpc-error-code">`rpc.jsonrpc.error_code`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Use string representation of the error code on the `rpc.response.status_code` attribute. | int | Deprecated, use string representation on the `rpc.response.status_code` attribute instead. | `-32700`; `100` |
-| <a id="rpc-jsonrpc-error-message" href="#rpc-jsonrpc-error-message">`rpc.jsonrpc.error_message`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Use the span status description or `error.message` attribute on other signals. | string | Deprecated, use span status description or `error.message` attribute on other signals. | `Parse error`; `User already exists` |
+| <a id="rpc-jsonrpc-error-message" href="#rpc-jsonrpc-error-message">`rpc.jsonrpc.error_message`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Use the span status description when reporting JSON-RPC spans. | string | Deprecated, use the span status description when reporting JSON-RPC spans. | `Parse error`; `User already exists` |
 | <a id="rpc-jsonrpc-request-id" href="#rpc-jsonrpc-request-id">`rpc.jsonrpc.request_id`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `jsonrpc.request.id`. | string | Deprecated, use `jsonrpc.request.id` instead. | `10`; `request-7`; `` |
 | <a id="rpc-jsonrpc-version" href="#rpc-jsonrpc-version">`rpc.jsonrpc.version`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `jsonrpc.protocol.version`. | string | Deprecated, use `jsonrpc.protocol.version` instead. | `2.0`; `1.0` |
 | <a id="rpc-service" href="#rpc-service">`rpc.service`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Value should be included in `rpc.method` which is expected to be a fully-qualified name. | string | Deprecated, use fully-qualified `rpc.method` instead. | `myservice.EchoService` |

model/error/deprecated/registry-deprecated.yaml

@@ -0,0 +1,22 @@
+groups:
+  - id: registry.error.deprecated
+    type: attribute_group
+    display_name: Deprecated Error Attributes
+    brief: >
+      This document defines deprecated attributes used to report an error.
+    attributes:
+      - id: error.message
+        type: string
+        stability: development
+        examples: ["Unexpected input type: string", "The user has exceeded their storage quota"]
+        brief: A message providing more detail about an error in human-readable form.
+        note: |
+          `error.message` should provide additional context and detail about an error.
+          It is NOT RECOMMENDED to duplicate the value of `error.type` in `error.message`.
+          It is also NOT RECOMMENDED to duplicate the value of `exception.message` in `error.message`.
+
+          `error.message` is NOT RECOMMENDED for metrics or spans due to its unbounded cardinality and overlap with span status.
+        deprecated:
+          reason: obsoleted
+          note: Use domain-specific error message attribute. For example, use
+            `feature_flag.error.message` for feature flag errors.

model/error/registry.yaml

@@ -37,14 +37,3 @@ groups:
 
           - Use a domain-specific attribute
           - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
-      - id: error.message
-        type: string
-        stability: development
-        examples: ["Unexpected input type: string", "The user has exceeded their storage quota"]
-        brief: A message providing more detail about an error in human-readable form.
-        note: |
-          `error.message` should provide additional context and detail about an error.
-          It is NOT RECOMMENDED to duplicate the value of `error.type` in `error.message`.
-          It is also NOT RECOMMENDED to duplicate the value of `exception.message` in `error.message`.
-
-          `error.message` is NOT RECOMMENDED for metrics or spans due to its unbounded cardinality and overlap with span status.

model/feature-flags/deprecated/registry-deprecated.yaml

@@ -70,9 +70,9 @@ groups:
         examples: ["red", "true", "on"]
       - id: feature_flag.evaluation.error.message
         type: string
-        brief: 'Deprecated, use `error.message` instead.'
+        brief: 'Deprecated, use `feature_flag.error.message` instead.'
         stability: development
         deprecated:
           reason: renamed
-          renamed_to: error.message
+          renamed_to: feature_flag.error.message
         examples: ["Flag `header-color` expected type `string` but found type `number`"]

model/feature-flags/events.yaml

@@ -51,9 +51,9 @@ groups:
           | `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
           | `type_mismatch` | The type of the flag value does not match the expected type. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
           | `general` | The error was for a reason not enumerated above. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
-      - ref: error.message
+      - ref: feature_flag.error.message
         requirement_level:
           recommended: If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error.
         note: >
           Should not simply duplicate the value of `error.type`, but should provide more context.
-          For example, if `error.type` is `invalid_context` the `error.message` may enumerate which context keys are missing or invalid.
+          For example, if `error.type` is `invalid_context` the `feature_flag.error.message` may enumerate which context keys are missing or invalid.

model/feature-flags/registry.yaml

@@ -99,3 +99,9 @@ groups:
 
           It may be desirable to redact or otherwise limit the size and scope of `feature_flag.result.value` if possible.
           Because the evaluated flag value is unstructured and may be any type, it is left to the instrumentation author to determine how best to achieve this.
+      - id: feature_flag.error.message
+        type: string
+        stability: release_candidate
+        brief: >
+          A message providing more detail about an error that occurred during feature flag evaluation in human-readable form.
+        examples: ["Unexpected input type: string", "The user has exceeded their storage quota"]

model/rpc/deprecated/registry-deprecated.yaml

@@ -218,11 +218,11 @@ groups:
       - id: rpc.jsonrpc.error_message
         type: string
         stability: development
-        brief: "Deprecated, use span status description or `error.message` attribute on other signals."
+        brief: "Deprecated, use the span status description when reporting JSON-RPC spans."
         examples: ['Parse error', 'User already exists']
         deprecated:
           reason: uncategorized
-          note: "Use the span status description or `error.message` attribute on other signals."
+          note: "Use the span status description when reporting JSON-RPC spans."
       - id: rpc.system
         brief: 'Deprecated, use `rpc.system.name` attribute instead.'
         deprecated: