diff --git a/.chloggen/deprecate-error-message.yaml b/.chloggen/deprecate-error-message.yaml new file mode 100644 index 0000000000..06d625af17 --- /dev/null +++ b/.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] diff --git a/docs/feature-flags/feature-flags-events.md b/docs/feature-flags/feature-flags-events.md index 32d88aa783..d3be8fe093 100644 --- a/docs/feature-flags/feature-flags-events.md +++ b/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. --- diff --git a/docs/registry/attributes/error.md b/docs/registry/attributes/error.md index 72256e6024..3da89f7c60 100644 --- a/docs/registry/attributes/error.md +++ b/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 | | --- | --- | --- | --- | --- | -| `error.message` | ![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` | -| `error.type` | ![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` | +| `error.type` | ![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 | +| --- | --- | --- | --- | --- | +| `error.message` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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. diff --git a/docs/registry/attributes/feature-flag.md b/docs/registry/attributes/feature-flag.md index 9150fad400..353f3c2d64 100644 --- a/docs/registry/attributes/feature-flag.md +++ b/docs/registry/attributes/feature-flag.md @@ -15,6 +15,7 @@ This document defines attributes for Feature Flags. | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | | `feature_flag.context.id` | ![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` | +| `feature_flag.error.message` | ![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` | | `feature_flag.key` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | string | The lookup key of the feature flag. | `logo-color` | | `feature_flag.provider.name` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | string | Identifies the feature flag provider. | `Flag Manager` | | `feature_flag.result.reason` | ![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 | | --- | --- | --- | --- | --- | -| `feature_flag.evaluation.error.message` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `error.message`. | string | Deprecated, use `error.message` instead. | `Flag `header-color` expected type `string` but found type `number`` | +| `feature_flag.evaluation.error.message` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.error.message`. | string | Deprecated, use `feature_flag.error.message` instead. | `Flag `header-color` expected type `string` but found type `number`` | | `feature_flag.evaluation.reason` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.result.reason`. | string | Deprecated, use `feature_flag.result.reason` instead. | `static`; `targeting_match`; `error`; `default` | | `feature_flag.provider_name` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.provider.name`. | string | Deprecated, use `feature_flag.provider.name` instead. | `Flag Manager` | | `feature_flag.variant` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.result.variant`. | string | Deprecated, use `feature_flag.result.variant` instead. | `red`; `true`; `on` | diff --git a/docs/registry/attributes/rpc.md b/docs/registry/attributes/rpc.md index 3a4d561725..e1db130e90 100644 --- a/docs/registry/attributes/rpc.md +++ b/docs/registry/attributes/rpc.md @@ -107,7 +107,7 @@ Deprecated rpc message attributes. | `rpc.grpc.response.metadata.` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `rpc.response.metadata`. | string[] | Deprecated, use `rpc.response.metadata` instead. | `["attribute_value"]` | | `rpc.grpc.status_code` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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` | | `rpc.jsonrpc.error_code` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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` | -| `rpc.jsonrpc.error_message` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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` | +| `rpc.jsonrpc.error_message` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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` | | `rpc.jsonrpc.request_id` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `jsonrpc.request.id`. | string | Deprecated, use `jsonrpc.request.id` instead. | `10`; `request-7`; `` | | `rpc.jsonrpc.version` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `jsonrpc.protocol.version`. | string | Deprecated, use `jsonrpc.protocol.version` instead. | `2.0`; `1.0` | | `rpc.service` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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` | diff --git a/model/error/deprecated/registry-deprecated.yaml b/model/error/deprecated/registry-deprecated.yaml new file mode 100644 index 0000000000..c147dd3b5a --- /dev/null +++ b/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. diff --git a/model/error/registry.yaml b/model/error/registry.yaml index 927c8c636a..7bda26b5aa 100644 --- a/model/error/registry.yaml +++ b/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. diff --git a/model/feature-flags/deprecated/registry-deprecated.yaml b/model/feature-flags/deprecated/registry-deprecated.yaml index 0ea6c7aca0..508b820406 100644 --- a/model/feature-flags/deprecated/registry-deprecated.yaml +++ b/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`"] diff --git a/model/feature-flags/events.yaml b/model/feature-flags/events.yaml index 06ff62878a..3a86060c54 100644 --- a/model/feature-flags/events.yaml +++ b/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. diff --git a/model/feature-flags/registry.yaml b/model/feature-flags/registry.yaml index 974ba14662..dd7178ced6 100644 --- a/model/feature-flags/registry.yaml +++ b/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"] diff --git a/model/rpc/deprecated/registry-deprecated.yaml b/model/rpc/deprecated/registry-deprecated.yaml index edd332ff08..b107b1ac97 100644 --- a/model/rpc/deprecated/registry-deprecated.yaml +++ b/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: