From 820fa6dbea2faba344552f9e0f7156d6286e1466 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 12 Mar 2025 09:27:52 -0400 Subject: [PATCH 1/6] Rename `evaluation` to `result` for feature flag evaluation result attributes --- .chloggen/ff-result-namespace.yaml | 22 ++++++++++++++++++++++ docs/attributes-registry/feature-flag.md | 8 ++++---- docs/feature-flags/feature-flags-logs.md | 10 +++++----- model/feature-flags/logs.yaml | 4 ++-- model/feature-flags/registry.yaml | 4 ++-- schema-next.yaml | 7 +++++++ 6 files changed, 42 insertions(+), 13 deletions(-) create mode 100755 .chloggen/ff-result-namespace.yaml diff --git a/.chloggen/ff-result-namespace.yaml b/.chloggen/ff-result-namespace.yaml new file mode 100755 index 0000000000..4d71964719 --- /dev/null +++ b/.chloggen/ff-result-namespace.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: Rename `evaluation` to `result` for feature flag evaluation result attributes + +# 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: [] + +# (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 803cb30796..5b0b3138c8 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -11,21 +11,21 @@ This document defines attributes for Feature Flags. |---|---|---|---|---| | `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.evaluation.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) | | `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) | +| `feature_flag.result.variant` | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | ![Development](https://img.shields.io/badge/-development-blue) | | `feature_flag.set.id` | 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` | ![Development](https://img.shields.io/badge/-development-blue) | -| `feature_flag.variant` | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | ![Development](https://img.shields.io/badge/-development-blue) | | `feature_flag.version` | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | ![Development](https://img.shields.io/badge/-development-blue) | -**[1] `feature_flag.variant`:** A semantic identifier, commonly referred to as a variant, provides a means +**[1] `feature_flag.result.variant`:** A semantic identifier, commonly referred to as a variant, provides a means 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`. --- -`feature_flag.evaluation.reason` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`feature_flag.result.reason` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 80b7c5525d..435f9b2d2e 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -60,11 +60,11 @@ 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.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) | +| [`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) | | [`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.evaluation.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.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) | | [`feature_flag.version`](/docs/attributes-registry/feature-flag.md) | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -83,12 +83,12 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu **[2] `error.type`:** If and only if an error occurred during flag evaluation. -**[3] `feature_flag.variant`:** A semantic identifier, commonly referred to as a variant, provides a means +**[3] `feature_flag.result.variant`:** A semantic identifier, commonly referred to as a variant, provides a means 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`. -**[4] `feature_flag.variant`:** If feature flag provider supplies a variant or equivalent concept. +**[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`. @@ -102,7 +102,7 @@ For example, the variant `red` maybe be used for the value `#c05543`. --- -`feature_flag.evaluation.reason` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`feature_flag.result.reason` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| diff --git a/model/feature-flags/logs.yaml b/model/feature-flags/logs.yaml index fa5429af50..22837ea7a2 100644 --- a/model/feature-flags/logs.yaml +++ b/model/feature-flags/logs.yaml @@ -15,7 +15,7 @@ groups: attributes: - ref: feature_flag.key requirement_level: required - - ref: feature_flag.variant + - ref: feature_flag.result.variant requirement_level: conditionally_required: If feature flag provider supplies a variant or equivalent concept. - ref: feature_flag.provider_name @@ -26,7 +26,7 @@ groups: requirement_level: recommended - ref: feature_flag.set.id requirement_level: recommended - - ref: feature_flag.evaluation.reason + - ref: feature_flag.result.reason requirement_level: recommended - ref: error.type examples: ["provider_not_ready", "targeting_key_missing", "provider_fatal", "general"] diff --git a/model/feature-flags/registry.yaml b/model/feature-flags/registry.yaml index 264d6945be..b86756486f 100644 --- a/model/feature-flags/registry.yaml +++ b/model/feature-flags/registry.yaml @@ -16,7 +16,7 @@ groups: stability: development brief: Identifies the feature flag provider. examples: ["Flag Manager"] - - id: feature_flag.variant + - id: feature_flag.result.variant type: string stability: development examples: ["red", "true", "on"] @@ -45,7 +45,7 @@ groups: examples: ["proj-1", "ab98sgs", "service1/dev"] brief: > The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. - - id: feature_flag.evaluation.reason + - id: feature_flag.result.reason type: members: - id: static diff --git a/schema-next.yaml b/schema-next.yaml index 107d5861a8..c7c7dd5a48 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,6 +2,13 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/1.31.0 versions: next: + all: + changes: + # todo link + - rename_attributes: + attribute_map: + feature_flag.evaluation.reason: feature_flag.result.reason + feature_flag.evaluation.variant: feature_flag.result.variant 1.31.0: all: changes: From fc9ead6394f7c1bc5c4e9e884e3d38102ce98673 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 12 Mar 2025 09:43:42 -0400 Subject: [PATCH 2/6] Add links to schema and chlog --- .chloggen/ff-result-namespace.yaml | 2 +- schema-next.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.chloggen/ff-result-namespace.yaml b/.chloggen/ff-result-namespace.yaml index 4d71964719..15f20b016c 100755 --- a/.chloggen/ff-result-namespace.yaml +++ b/.chloggen/ff-result-namespace.yaml @@ -14,7 +14,7 @@ note: Rename `evaluation` to `result` for feature flag evaluation result attribu # 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: [] +issues: [1989] # (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. diff --git a/schema-next.yaml b/schema-next.yaml index c7c7dd5a48..e2b4b52ab2 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -4,7 +4,7 @@ versions: next: all: changes: - # todo link + # https://github.com/open-telemetry/semantic-conventions/pull/1989 - rename_attributes: attribute_map: feature_flag.evaluation.reason: feature_flag.result.reason From 1160a12fa951630f9b68bb1004e26bbd87602a19 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 12 Mar 2025 09:48:01 -0400 Subject: [PATCH 3/6] Add deprecated ff attributes --- .../deprecated/registry-deprecated.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 model/feature-flags/deprecated/registry-deprecated.yaml diff --git a/model/feature-flags/deprecated/registry-deprecated.yaml b/model/feature-flags/deprecated/registry-deprecated.yaml new file mode 100644 index 0000000000..70bd6e055d --- /dev/null +++ b/model/feature-flags/deprecated/registry-deprecated.yaml @@ -0,0 +1,18 @@ +groups: + - id: registry.feature_flag.deprecated + type: attribute_group + display_name: Deprecated Feature Flag Attributes + brief: "Describes deprecated feature flag attributes." + attributes: + - id: feature_flag.evaluation.reason + type: string + brief: 'Deprecated, use `feature_flag.result.reason` instead.' + stability: development + deprecated: "Replaced by `feature_flag.result.reason`." + examples: ["static", "targeting_match", "error", "default"] + - id: feature_flag.variant + type: string + brief: 'Deprecated, use `feature_flag.result.variant` instead.' + stability: development + deprecated: "Replaced by `feature_flag.result.variant`." + examples: ["red", "true", "on"] \ No newline at end of file From f9658fa548af0e6a51c3a2dde18e24862a9936a1 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 12 Mar 2025 09:50:50 -0400 Subject: [PATCH 4/6] Fix deprecated registry --- .../deprecated/registry-deprecated.yaml | 70 ++++++++++++++----- 1 file changed, 53 insertions(+), 17 deletions(-) diff --git a/model/feature-flags/deprecated/registry-deprecated.yaml b/model/feature-flags/deprecated/registry-deprecated.yaml index 70bd6e055d..e7655bdf2e 100644 --- a/model/feature-flags/deprecated/registry-deprecated.yaml +++ b/model/feature-flags/deprecated/registry-deprecated.yaml @@ -1,18 +1,54 @@ groups: - - id: registry.feature_flag.deprecated - type: attribute_group - display_name: Deprecated Feature Flag Attributes - brief: "Describes deprecated feature flag attributes." - attributes: - - id: feature_flag.evaluation.reason - type: string - brief: 'Deprecated, use `feature_flag.result.reason` instead.' - stability: development - deprecated: "Replaced by `feature_flag.result.reason`." - examples: ["static", "targeting_match", "error", "default"] - - id: feature_flag.variant - type: string - brief: 'Deprecated, use `feature_flag.result.variant` instead.' - stability: development - deprecated: "Replaced by `feature_flag.result.variant`." - examples: ["red", "true", "on"] \ No newline at end of file + - id: registry.feature_flag.deprecated + type: attribute_group + display_name: Deprecated Feature Flag Attributes + brief: "Describes deprecated feature flag attributes." + attributes: + - id: feature_flag.evaluation.reason + members: + - id: static + value: "static" + brief: The resolved value is static (no dynamic evaluation). + stability: development + - id: default + value: "default" + brief: The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). + stability: development + - id: targeting_match + value: "targeting_match" + brief: The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. + stability: development + - id: split + value: "split" + brief: The resolved value was the result of pseudorandom assignment. + stability: development + - id: cached + value: "cached" + brief: The resolved value was retrieved from cache. + stability: development + - id: disabled + value: "disabled" + brief: The resolved value was the result of the flag being disabled in the management system. + stability: development + - id: unknown + value: "unknown" + brief: The reason for the resolved value could not be determined. + stability: development + - id: stale + value: "stale" + brief: The resolved value is non-authoritative or possibly out of date + stability: development + - id: error + value: "error" + brief: The resolved value was the result of an error. + stability: development + brief: 'Deprecated, use `feature_flag.result.reason` instead.' + stability: development + deprecated: "Replaced by `feature_flag.result.reason`." + examples: ["static", "targeting_match", "error", "default"] + - id: feature_flag.variant + type: string + brief: 'Deprecated, use `feature_flag.result.variant` instead.' + stability: development + deprecated: "Replaced by `feature_flag.result.variant`." + examples: ["red", "true", "on"] From f13c241d8e0db4fe0f505722afcd4481092e93e6 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 12 Mar 2025 09:53:17 -0400 Subject: [PATCH 5/6] Fix yaml for real this time and regenerate table --- docs/attributes-registry/feature-flag.md | 28 +++++++++++++++++++ .../deprecated/registry-deprecated.yaml | 1 + 2 files changed, 29 insertions(+) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 5b0b3138c8..76dd3056a4 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -3,6 +3,9 @@ # Feature flag +- [Feature Flag Attributes](#feature-flag-attributes) +- [Deprecated Feature Flag Attributes](#deprecated-feature-flag-attributes) + ## Feature Flag Attributes This document defines attributes for Feature Flags. @@ -38,3 +41,28 @@ For example, the variant `red` maybe be used for the value `#c05543`. | `static` | The resolved value is static (no dynamic evaluation). | ![Development](https://img.shields.io/badge/-development-blue) | | `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Development](https://img.shields.io/badge/-development-blue) | | `unknown` | The reason for the resolved value could not be determined. | ![Development](https://img.shields.io/badge/-development-blue) | + +## Deprecated Feature Flag Attributes + +Describes deprecated feature flag attributes. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `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`. | + +--- + +`feature_flag.evaluation.reason` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `cached` | The resolved value was retrieved from cache. | ![Development](https://img.shields.io/badge/-development-blue) | +| `default` | The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). | ![Development](https://img.shields.io/badge/-development-blue) | +| `disabled` | The resolved value was the result of the flag being disabled in the management system. | ![Development](https://img.shields.io/badge/-development-blue) | +| `error` | The resolved value was the result of an error. | ![Development](https://img.shields.io/badge/-development-blue) | +| `split` | The resolved value was the result of pseudorandom assignment. | ![Development](https://img.shields.io/badge/-development-blue) | +| `stale` | The resolved value is non-authoritative or possibly out of date | ![Development](https://img.shields.io/badge/-development-blue) | +| `static` | The resolved value is static (no dynamic evaluation). | ![Development](https://img.shields.io/badge/-development-blue) | +| `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Development](https://img.shields.io/badge/-development-blue) | +| `unknown` | The reason for the resolved value could not be determined. | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/feature-flags/deprecated/registry-deprecated.yaml b/model/feature-flags/deprecated/registry-deprecated.yaml index e7655bdf2e..233f3c5e8a 100644 --- a/model/feature-flags/deprecated/registry-deprecated.yaml +++ b/model/feature-flags/deprecated/registry-deprecated.yaml @@ -5,6 +5,7 @@ groups: brief: "Describes deprecated feature flag attributes." attributes: - id: feature_flag.evaluation.reason + type: members: - id: static value: "static" From 54bb02d5fa1a542cd1d4db6c5ce4d48c93f94f2a Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Fri, 28 Mar 2025 10:36:03 -0400 Subject: [PATCH 6/6] Update schema-next.yaml Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- schema-next.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schema-next.yaml b/schema-next.yaml index e2b4b52ab2..76c094c906 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -8,7 +8,7 @@ versions: - rename_attributes: attribute_map: feature_flag.evaluation.reason: feature_flag.result.reason - feature_flag.evaluation.variant: feature_flag.result.variant + feature_flag.variant: feature_flag.result.variant 1.31.0: all: changes: