From bb96516cededed6312de03eff79cd8cc15cfa942 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 8 Apr 2025 02:30:13 +0100 Subject: [PATCH] Use generic `error.message` in feature flag evaluation event (#1994) Co-authored-by: Liudmila Molkova --- .chloggen/ff-generic-error.yaml | 22 +++++++++++++++++++ docs/attributes-registry/feature-flag.md | 2 +- docs/feature-flags/feature-flags-logs.md | 6 +++-- .../deprecated/registry-deprecated.yaml | 6 +++++ model/feature-flags/events.yaml | 7 ++++-- model/feature-flags/registry.yaml | 5 ----- schema-next.yaml | 6 +++++ 7 files changed, 44 insertions(+), 10 deletions(-) create mode 100755 .chloggen/ff-generic-error.yaml diff --git a/.chloggen/ff-generic-error.yaml b/.chloggen/ff-generic-error.yaml new file mode 100755 index 000000000..473a97165 --- /dev/null +++ b/.chloggen/ff-generic-error.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: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: feature_flag + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Use generic `error.message` in feature flag evaluation event + +# 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: [1994] + +# (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: diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 76dd3056a..9383ce9e4 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -13,7 +13,6 @@ This document defines attributes for Feature Flags. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `feature_flag.context.id` | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | ![Development](https://img.shields.io/badge/-development-blue) | -| `feature_flag.evaluation.error.message` | string | A message explaining the nature of an error occurring during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | ![Development](https://img.shields.io/badge/-development-blue) | | `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` | ![Development](https://img.shields.io/badge/-development-blue) | | `feature_flag.provider_name` | string | Identifies the feature flag provider. | `Flag Manager` | ![Development](https://img.shields.io/badge/-development-blue) | | `feature_flag.result.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -48,6 +47,7 @@ Describes deprecated feature flag attributes. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| +| `feature_flag.evaluation.error.message` | string | Deprecated, use `error.message` instead. | `Flag `header-color` expected type `string` but found type `number`` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `error.message`. | | `feature_flag.evaluation.reason` | string | Deprecated, use `feature_flag.result.reason` instead. | `static`; `targeting_match`; `error`; `default` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.result.reason`. | | `feature_flag.variant` | string | Deprecated, use `feature_flag.result.variant` instead. | `red`; `true`; `on` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.result.variant`. | diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index aa71aa411..ab7f25b2b 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -61,8 +61,8 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`feature_flag.result.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [3] | `red`; `true`; `on` | `Conditionally Required` [4] | ![Development](https://img.shields.io/badge/-development-blue) | +| [`error.message`](/docs/attributes-registry/error.md) | string | A message providing more detail about an error in human-readable form. [5] | `Unexpected input type: string`; `The user has exceeded their storage quota` | `Recommended` [6] | ![Development](https://img.shields.io/badge/-development-blue) | | [`feature_flag.context.id`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`feature_flag.evaluation.error.message`](/docs/attributes-registry/feature-flag.md) | string | A message explaining the nature of an error occurring during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | `Recommended` [5] | ![Development](https://img.shields.io/badge/-development-blue) | | [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`feature_flag.result.reason`](/docs/attributes-registry/feature-flag.md) | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`feature_flag.set.id`](/docs/attributes-registry/feature-flag.md) | 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` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -90,7 +90,9 @@ For example, the variant `red` maybe be used for the value `#c05543`. **[4] `feature_flag.result.variant`:** If feature flag provider supplies a variant or equivalent concept. -**[5] `feature_flag.evaluation.error.message`:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`. +**[5] `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. + +**[6] `error.message`:** If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error. --- diff --git a/model/feature-flags/deprecated/registry-deprecated.yaml b/model/feature-flags/deprecated/registry-deprecated.yaml index 233f3c5e8..89806f476 100644 --- a/model/feature-flags/deprecated/registry-deprecated.yaml +++ b/model/feature-flags/deprecated/registry-deprecated.yaml @@ -53,3 +53,9 @@ groups: stability: development deprecated: "Replaced by `feature_flag.result.variant`." examples: ["red", "true", "on"] + - id: feature_flag.evaluation.error.message + type: string + brief: 'Deprecated, use `error.message` instead.' + stability: development + deprecated: "Replaced by `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 22837ea7a..91a95caba 100644 --- a/model/feature-flags/events.yaml +++ b/model/feature-flags/events.yaml @@ -46,9 +46,12 @@ groups: | `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Development](https://img.shields.io/badge/-development-blue) | | `type_mismatch` | The type of the flag value does not match the expected type. | ![Development](https://img.shields.io/badge/-development-blue) | | `general` | The error was for a reason not enumerated above. | ![Development](https://img.shields.io/badge/-development-blue) | - - ref: feature_flag.evaluation.error.message + - ref: error.message requirement_level: - recommended: If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`. + 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. body: id: feature_flag.evaluation type: map diff --git a/model/feature-flags/registry.yaml b/model/feature-flags/registry.yaml index b86756486..de949aaf2 100644 --- a/model/feature-flags/registry.yaml +++ b/model/feature-flags/registry.yaml @@ -88,8 +88,3 @@ groups: examples: ["static", "targeting_match", "error", "default"] brief: > The reason code which shows how a feature flag value was determined. - - id: feature_flag.evaluation.error.message - type: string - stability: development - examples: ["Flag `header-color` expected type `string` but found type `number`"] - brief: A message explaining the nature of an error occurring during flag evaluation. diff --git a/schema-next.yaml b/schema-next.yaml index 9f0d41f74..ef29ae1ff 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,6 +2,12 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/1.31.0 versions: next: + all: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/1994 + - rename_attributes: + attribute_map: + feature_flag.evaluation.error.message: error.message 1.32.0: all: changes: