From 64cc6e178596858bec285f9b887e69325649cf40 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 30 Sep 2024 09:48:31 -0400 Subject: [PATCH 01/37] Feature Flag: feature_flag.evaluation event --- docs/attributes-registry/feature-flag.md | 14 +++-- docs/feature-flags/feature-flags-logs.md | 14 +++-- docs/feature-flags/feature-flags-spans.md | 76 ----------------------- model/feature-flag/events.yaml | 16 +++-- model/feature-flag/logs.yaml | 21 +++++-- model/feature-flag/registry.yaml | 27 +++++++- 6 files changed, 72 insertions(+), 96 deletions(-) delete mode 100644 docs/feature-flags/feature-flags-spans.md diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index e752cc6172..d19a6e4a77 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -10,11 +10,15 @@ This document defines attributes for Feature Flags. -| Attribute | Type | Description | Examples | Stability | -| ---------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------- | -| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.provider_name` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.environment.id` | string | The identifier of the environment which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.provider.id` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.value` | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.version` | string | The version of the ruleset used during the evaluation. Could use a hash if a version is not available. | `1`; `01ABCDEF` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 4ab5622ed5..a0faa2d526 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -37,20 +37,24 @@ context. The table below indicates which attributes should be added to the [LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. - + -The event name MUST be `feature_flag`. +The event name MUST be `feature_flag.evaluation`. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.environment.id`](/docs/attributes-registry/feature-flag.md) | string | The identifier of the environment which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.provider.id`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.version`](/docs/attributes-registry/feature-flag.md) | string | The version of the ruleset used during the evaluation. Could use a hash if a version is not available. | `1`; `01ABCDEF` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.value`](/docs/attributes-registry/feature-flag.md) | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can diff --git a/docs/feature-flags/feature-flags-spans.md b/docs/feature-flags/feature-flags-spans.md deleted file mode 100644 index f877fce133..0000000000 --- a/docs/feature-flags/feature-flags-spans.md +++ /dev/null @@ -1,76 +0,0 @@ - - -# Semantic Conventions for Feature Flags in Spans - -**Status**: [Experimental][DocumentStatus] - -This document defines semantic conventions for recording dynamic feature flag -evaluations within a transaction as span events. -To record an evaluation outside of a transaction context, consider -[recording it as a log record](feature-flags-logs.md). - - - - - -- [Motivation](#motivation) -- [Overview](#overview) -- [Convention](#convention) - - - -## Motivation - -Features flags are commonly used in modern applications to decouple feature releases from deployments. -Many feature flagging tools support the ability to update flag configurations in near real-time from a remote feature flag management service. -They also commonly allow rulesets to be defined that return values based on contextual information. -For example, a feature could be enabled only for a specific subset of users based on context (e.g. users email domain, membership tier, country). - -Since feature flags are dynamic and affect runtime behavior, it's important to collect relevant feature flag telemetry signals. -This can be used to determine the impact a feature has on a request, enabling enhanced observability use cases, such as A/B testing or progressive feature releases. - -## Overview - -The following semantic convention defines how feature flags can be represented as an `Event` in OpenTelemetry. -The terminology was defined in the [OpenFeature specification](https://docs.openfeature.dev/docs/specification/), which represents an industry consensus. -It's intended to be vendor neutral and provide flexibility for current and future use cases. - -## Convention - -A flag evaluation SHOULD be recorded as an Event on the span during which it occurred. - - - - - - - - -The event name MUST be `feature_flag`. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** 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`. - -A stringified version of the value can be used in situations where a -semantic identifier is unavailable. String representation of the value -should be determined by the implementer. - - - - - - - - - -[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/feature-flag/events.yaml b/model/feature-flag/events.yaml index 8aae493385..3d9d4d457b 100644 --- a/model/feature-flag/events.yaml +++ b/model/feature-flag/events.yaml @@ -1,14 +1,22 @@ groups: - - id: feature_flag + - id: feature_flag.evaluation type: event - name: feature_flag + name: feature_flag.evaluation brief: > This semantic convention defines the attributes used to represent a feature flag evaluation as an event. attributes: - ref: feature_flag.key requirement_level: required - - ref: feature_flag.provider_name - requirement_level: recommended - ref: feature_flag.variant + requirement_level: required + - ref: feature_flag.provider.id + requirement_level: recommended + - ref: feature_flag.context.id + requirement_level: recommended + - ref: feature_flag.version + requirement_level: recommended + - ref: feature_flag.environment.id requirement_level: recommended + - ref: feature_flag.value + requirement_level: optional diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 4530096de7..fee926237a 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -1,11 +1,22 @@ groups: - - id: log-feature_flag + - id: feature_flag.evaluation type: event - name: feature_flag + name: feature_flag.evaluation brief: > - This document defines attributes for feature flag evaluations - represented using Log Records. + This semantic convention defines the attributes used to represent a + feature flag evaluation as an event. attributes: - ref: feature_flag.key - - ref: feature_flag.provider_name + requirement_level: required - ref: feature_flag.variant + requirement_level: required + - ref: feature_flag.provider.id + requirement_level: recommended + - ref: feature_flag.context.id + requirement_level: recommended + - ref: feature_flag.version + requirement_level: recommended + - ref: feature_flag.environment.id + requirement_level: recommended + - ref: feature_flag.value + requirement_level: opt_in diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 1533d685ec..2e742ef3c0 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -10,7 +10,7 @@ groups: stability: experimental brief: The unique identifier of the feature flag. examples: ["logo-color"] - - id: feature_flag.provider_name + - id: feature_flag.provider.id type: string stability: experimental brief: The name of the service provider that performs the flag evaluation. @@ -31,3 +31,28 @@ groups: A stringified version of the value can be used in situations where a semantic identifier is unavailable. String representation of the value should be determined by the implementer. + - id: feature_flag.value + type: string + stability: experimental + examples: ["#ff0000", "1", "true"] + brief: > + The evaluated value of the feature flag. + - id: feature_flag.context.id + type: string + stability: experimental + examples: ["5157782b-2203-4c80-a857-dbbd5e7761db"] + brief: > + The unique identifier for the flag evaluation context. For example, the targeting key. + - id: feature_flag.version + type: string + stability: experimental + examples: ["1", "01ABCDEF"] + brief: > + The version of the ruleset used during the evaluation. Could use a hash if a version is not available. + - id: feature_flag.environment.id + type: string + stability: experimental + examples: ["proj-1", "ab98sgs"] + brief: > + The identifier of the environment which the feature flag belongs to in a flag management system. + From 9d70d52f1f7db98ddc414341757cd456c948a5cf Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 30 Sep 2024 09:56:17 -0400 Subject: [PATCH 02/37] Remove ff events.yaml for now --- model/feature-flag/events.yaml | 22 ---------------------- 1 file changed, 22 deletions(-) delete mode 100644 model/feature-flag/events.yaml diff --git a/model/feature-flag/events.yaml b/model/feature-flag/events.yaml deleted file mode 100644 index 3d9d4d457b..0000000000 --- a/model/feature-flag/events.yaml +++ /dev/null @@ -1,22 +0,0 @@ -groups: - - id: feature_flag.evaluation - type: event - name: feature_flag.evaluation - brief: > - This semantic convention defines the attributes used to represent a - feature flag evaluation as an event. - attributes: - - ref: feature_flag.key - requirement_level: required - - ref: feature_flag.variant - requirement_level: required - - ref: feature_flag.provider.id - requirement_level: recommended - - ref: feature_flag.context.id - requirement_level: recommended - - ref: feature_flag.version - requirement_level: recommended - - ref: feature_flag.environment.id - requirement_level: recommended - - ref: feature_flag.value - requirement_level: optional From 17661adc811598ce3d1094dd56ce83934401fc7c Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 30 Sep 2024 10:01:29 -0400 Subject: [PATCH 03/37] Deprecate --- docs/attributes-registry/feature-flag.md | 11 +++++++++++ .../feature-flag/deprecated/registry-deprecated.yaml | 12 ++++++++++++ 2 files changed, 23 insertions(+) create mode 100644 model/feature-flag/deprecated/registry-deprecated.yaml diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index d19a6e4a77..77605eace1 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -6,6 +6,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. @@ -28,3 +31,11 @@ For example, the variant `red` maybe be used for the value `#c05543`. A stringified version of the value can be used in situations where a semantic identifier is unavailable. String representation of the value should be determined by the implementer. + +## Deprecated Feature Flag Attributes + +Describes deprecated Feature Flag attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------------------- | ------ | --------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------ | +| `feature_flag.provider_name` | string | Deprecated, use `feature_flag.provider.id` instead. | `Flag Manager` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.provider.id`. | diff --git a/model/feature-flag/deprecated/registry-deprecated.yaml b/model/feature-flag/deprecated/registry-deprecated.yaml new file mode 100644 index 0000000000..7553382d95 --- /dev/null +++ b/model/feature-flag/deprecated/registry-deprecated.yaml @@ -0,0 +1,12 @@ +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.provider_name + type: string + brief: 'Deprecated, use `feature_flag.provider.id` instead.' + stability: experimental + deprecated: "Replaced by `feature_flag.provider.id`." + examples: ["Flag Manager"] \ No newline at end of file From 5a1315f55544e5fe68cf49b1731b3bef4ad22531 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 30 Sep 2024 10:20:02 -0400 Subject: [PATCH 04/37] Fix lint errors --- model/feature-flag/deprecated/registry-deprecated.yaml | 2 +- model/feature-flag/registry.yaml | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/model/feature-flag/deprecated/registry-deprecated.yaml b/model/feature-flag/deprecated/registry-deprecated.yaml index 7553382d95..7b4c33e763 100644 --- a/model/feature-flag/deprecated/registry-deprecated.yaml +++ b/model/feature-flag/deprecated/registry-deprecated.yaml @@ -9,4 +9,4 @@ groups: brief: 'Deprecated, use `feature_flag.provider.id` instead.' stability: experimental deprecated: "Replaced by `feature_flag.provider.id`." - examples: ["Flag Manager"] \ No newline at end of file + examples: ["Flag Manager"] diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 2e742ef3c0..bfd55ce2ef 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -55,4 +55,3 @@ groups: examples: ["proj-1", "ab98sgs"] brief: > The identifier of the environment which the feature flag belongs to in a flag management system. - From 778a5062e303164a744d0b48b2e36d7415f7a078 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 30 Sep 2024 10:22:07 -0400 Subject: [PATCH 05/37] Add changelog entry --- .chloggen/1140.yaml | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 .chloggen/1140.yaml diff --git a/.chloggen/1140.yaml b/.chloggen/1140.yaml new file mode 100644 index 0000000000..bfb24de677 --- /dev/null +++ b/.chloggen/1140.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: feature_flag +note: Define `feature_flag.evaluation` event. +issues: [1140] From 1b2d93976f03fd7faf42a6becf10e66de5734d87 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 14 Oct 2024 10:29:37 -0400 Subject: [PATCH 06/37] Update ff version to be clear a hash is not a specific recommendation --- docs/attributes-registry/feature-flag.md | 18 +++++++++--------- docs/feature-flags/feature-flags-logs.md | 2 +- model/feature-flag/registry.yaml | 2 +- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 77605eace1..4fb9c41598 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -13,15 +13,15 @@ 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.environment.id` | string | The identifier of the environment which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.provider.id` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.value` | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.version` | string | The version of the ruleset used during the evaluation. Could use a hash if a version is not available. | `1`; `01ABCDEF` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.environment.id` | string | The identifier of the environment which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.provider.id` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.value` | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 0ff3aa3dae..fbb35c3ed9 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -53,7 +53,7 @@ The event name MUST be `feature_flag.evaluation`. | [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.environment.id`](/docs/attributes-registry/feature-flag.md) | string | The identifier of the environment which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.provider.id`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.version`](/docs/attributes-registry/feature-flag.md) | string | The version of the ruleset used during the evaluation. Could use a hash if a version is not available. | `1`; `01ABCDEF` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.value`](/docs/attributes-registry/feature-flag.md) | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A semantic identifier, commonly referred to as a variant, provides a means diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index bfd55ce2ef..b3824c96be 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -48,7 +48,7 @@ groups: stability: experimental examples: ["1", "01ABCDEF"] brief: > - The version of the ruleset used during the evaluation. Could use a hash if a version is not available. + The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. - id: feature_flag.environment.id type: string stability: experimental From ab16aba0eebe617a71146ce55e6c0fea6fff499a Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 28 Oct 2024 09:20:22 -0400 Subject: [PATCH 07/37] Rename environment to flag set --- docs/attributes-registry/feature-flag.md | 2 +- docs/feature-flags/feature-flags-logs.md | 2 +- model/feature-flag/logs.yaml | 2 +- model/feature-flag/registry.yaml | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 1a78e6efdd..5830791d95 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -16,7 +16,7 @@ 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.environment.id` | string | The identifier of the environment which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.flag_set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.provider.id` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.value` | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index c603b3d703..baa0739b2d 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -55,7 +55,7 @@ This semantic convention defines the attributes used to represent a feature flag | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.environment.id`](/docs/attributes-registry/feature-flag.md) | string | The identifier of the environment which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.flag_set.id`](/docs/attributes-registry/feature-flag.md) | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.provider.id`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.value`](/docs/attributes-registry/feature-flag.md) | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index fee926237a..5d347f6e6b 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -16,7 +16,7 @@ groups: requirement_level: recommended - ref: feature_flag.version requirement_level: recommended - - ref: feature_flag.environment.id + - ref: feature_flag.flag_set.id requirement_level: recommended - ref: feature_flag.value requirement_level: opt_in diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 60a2de1f03..065b907c94 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -50,9 +50,9 @@ groups: examples: ["1", "01ABCDEF"] brief: > The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. - - id: feature_flag.environment.id + - id: feature_flag.flag_set.id type: string stability: experimental - examples: ["proj-1", "ab98sgs"] + examples: ["proj-1", "ab98sgs", "service1/dev"] brief: > - The identifier of the environment which the feature flag belongs to in a flag management system. + The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. From 4ffa81cb1a9ca737cb04de87f0b9d9f4d9759390 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 28 Oct 2024 09:22:43 -0400 Subject: [PATCH 08/37] Describe feature_flag.key as lookup key --- model/feature-flag/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 065b907c94..502a05b773 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -9,7 +9,7 @@ groups: - id: feature_flag.key type: string stability: experimental - brief: The unique identifier of the feature flag. + brief: The lookup key of the feature flag. examples: ["logo-color"] - id: feature_flag.provider.id type: string From 97b68d86ebfbc2a3ba4b5471a51db1e98aa5b323 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 28 Oct 2024 14:31:28 -0400 Subject: [PATCH 09/37] Update requirement level for variant and value --- docs/attributes-registry/feature-flag.md | 8 ++------ docs/feature-flags/feature-flags-logs.md | 14 +++++++------- model/feature-flag/logs.yaml | 8 ++++++-- model/feature-flag/registry.yaml | 7 +------ 4 files changed, 16 insertions(+), 21 deletions(-) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 5830791d95..fa98e30bed 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -17,10 +17,10 @@ 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.flag_set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.provider.id` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.value` | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.variant` | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A semantic identifier, commonly referred to as a variant, provides a means @@ -28,10 +28,6 @@ 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`. -A stringified version of the value can be used in situations where a -semantic identifier is unavailable. String representation of the value -should be determined by the implementer. - ## Deprecated Feature Flag Attributes Describes deprecated Feature Flag attributes. diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index baa0739b2d..9fcb1bc5c8 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -52,22 +52,22 @@ This semantic convention defines the attributes used to represent a feature flag | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.value`](/docs/attributes-registry/feature-flag.md) | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [2] | `red`; `true`; `on` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.flag_set.id`](/docs/attributes-registry/feature-flag.md) | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.provider.id`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.value`](/docs/attributes-registry/feature-flag.md) | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** A semantic identifier, commonly referred to as a variant, provides a means +**[1]:** If and only if feature flag provider does not provide variant or equivalent concept. Otherwise, `feature_flag.value` should be treated as opt-in. + +**[2]:** 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`. -A stringified version of the value can be used in situations where a -semantic identifier is unavailable. String representation of the value -should be determined by the implementer. +**[3]:** If feature flag provider provides a variant or equivalent concept. diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 5d347f6e6b..15f8ced809 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -9,7 +9,8 @@ groups: - ref: feature_flag.key requirement_level: required - ref: feature_flag.variant - requirement_level: required + requirement_level: + conditionally_required: If feature flag provider provides a variant or equivalent concept. - ref: feature_flag.provider.id requirement_level: recommended - ref: feature_flag.context.id @@ -19,4 +20,7 @@ groups: - ref: feature_flag.flag_set.id requirement_level: recommended - ref: feature_flag.value - requirement_level: opt_in + requirement_level: + conditionally_required: > + If and only if feature flag provider does not provide variant or equivalent concept. + Otherwise, `feature_flag.value` should be treated as opt-in. diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 502a05b773..26a47c63be 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -21,17 +21,12 @@ groups: stability: experimental examples: ["red", "true", "on"] brief: > - SHOULD be a semantic identifier for a value. If one is unavailable, a - stringified version of the value can be used. + A semantic identifier for an evaluated flag value. note: |- 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`. - - A stringified version of the value can be used in situations where a - semantic identifier is unavailable. String representation of the value - should be determined by the implementer. - id: feature_flag.value type: string stability: experimental From 4e70d70b344e19a09457971ef78df3173c19f550 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 28 Oct 2024 14:51:35 -0400 Subject: [PATCH 10/37] Avoid word repetition --- docs/feature-flags/feature-flags-logs.md | 4 ++-- model/feature-flag/logs.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 9fcb1bc5c8..20bc944e95 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -60,14 +60,14 @@ This semantic convention defines the attributes used to represent a feature flag | [`feature_flag.provider.id`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** If and only if feature flag provider does not provide variant or equivalent concept. Otherwise, `feature_flag.value` should be treated as opt-in. +**[1]:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `feature_flag.value` should be treated as opt-in. **[2]:** 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`. -**[3]:** If feature flag provider provides a variant or equivalent concept. +**[3]:** If feature flag provider supplies a variant or equivalent concept. diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 15f8ced809..a8b594dc34 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -10,7 +10,7 @@ groups: requirement_level: required - ref: feature_flag.variant requirement_level: - conditionally_required: If feature flag provider provides a variant or equivalent concept. + conditionally_required: If feature flag provider supplies a variant or equivalent concept. - ref: feature_flag.provider.id requirement_level: recommended - ref: feature_flag.context.id @@ -22,5 +22,5 @@ groups: - ref: feature_flag.value requirement_level: conditionally_required: > - If and only if feature flag provider does not provide variant or equivalent concept. + If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `feature_flag.value` should be treated as opt-in. From 78938e01c35537e4cbd8495ef7bfbf2bd413dae9 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 28 Oct 2024 14:58:17 -0400 Subject: [PATCH 11/37] Clarify permissiveness of provider id --- model/feature-flag/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 26a47c63be..44463093e7 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -14,7 +14,7 @@ groups: - id: feature_flag.provider.id type: string stability: experimental - brief: The name of the service provider that performs the flag evaluation. + brief: Any string which identifies the feature flag provider being used such as its name. examples: ["Flag Manager"] - id: feature_flag.variant type: string From e9e209ecfba15167aece2f320847a39b282933fa Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 4 Nov 2024 17:00:20 -0500 Subject: [PATCH 12/37] Rename flag_set to just set --- model/feature-flag/logs.yaml | 2 +- model/feature-flag/registry.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index a8b594dc34..a0f1833a1f 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -17,7 +17,7 @@ groups: requirement_level: recommended - ref: feature_flag.version requirement_level: recommended - - ref: feature_flag.flag_set.id + - ref: feature_flag.set.id requirement_level: recommended - ref: feature_flag.value requirement_level: diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 44463093e7..20a3f2e5d7 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -45,7 +45,7 @@ groups: examples: ["1", "01ABCDEF"] brief: > The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. - - id: feature_flag.flag_set.id + - id: feature_flag.set.id type: string stability: experimental examples: ["proj-1", "ab98sgs", "service1/dev"] From 9e68f157407fc9282821304e4e384b6ca154dfea Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 4 Nov 2024 17:07:41 -0500 Subject: [PATCH 13/37] Use system terminology to match db and gen_ai --- model/feature-flag/logs.yaml | 2 +- model/feature-flag/registry.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index a0f1833a1f..0073142aa5 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -11,7 +11,7 @@ groups: - ref: feature_flag.variant requirement_level: conditionally_required: If feature flag provider supplies a variant or equivalent concept. - - ref: feature_flag.provider.id + - ref: feature_flag.system requirement_level: recommended - ref: feature_flag.context.id requirement_level: recommended diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 20a3f2e5d7..cf032c2de5 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -11,10 +11,10 @@ groups: stability: experimental brief: The lookup key of the feature flag. examples: ["logo-color"] - - id: feature_flag.provider.id + - id: feature_flag.system type: string stability: experimental - brief: Any string which identifies the feature flag provider being used such as its name. + brief: Identifies the feature flag provider. examples: ["Flag Manager"] - id: feature_flag.variant type: string From 25f478364f17156658fcbbad3941f9eb00edbdd0 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 4 Nov 2024 17:13:13 -0500 Subject: [PATCH 14/37] Expand brief for flag evaluation event --- model/feature-flag/logs.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 0073142aa5..bf4c150bc8 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -5,6 +5,12 @@ groups: brief: > This semantic convention defines the attributes used to represent a feature flag evaluation as an event. + A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag + value is evaluated, which may happen many times over the course of an + application lifecycle. + For example, a website A/B testing different animations may evaluate a + flag each time a button is clicked. + A `feature_flag.evaluation` event is emitted on each evaluation even if the result is the same. attributes: - ref: feature_flag.key requirement_level: required From 51b7e45531811726a03a0b8dcb1ae41de9e6f2d1 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 5 Nov 2024 15:02:26 -0500 Subject: [PATCH 15/37] Move feature_flag.value to body field --- model/feature-flag/logs.yaml | 19 ++++++++++++++----- model/feature-flag/registry.yaml | 6 ------ 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index bf4c150bc8..7ae9efdce8 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -25,8 +25,17 @@ groups: requirement_level: recommended - ref: feature_flag.set.id requirement_level: recommended - - ref: feature_flag.value - requirement_level: - conditionally_required: > - If and only if feature flag provider does not supply variant or equivalent concept. - Otherwise, `feature_flag.value` should be treated as opt-in. + body: + id: feature_flag.evaluation + type: map + requirement_level: recommended + fields: + - id: value + type: undefined + stability: experimental + brief: The evaluated value of the feature flag. + requirement_level: + conditionally_required: > + If and only if feature flag provider does not supply variant or equivalent concept. + Otherwise, `value` should be treated as opt-in. + examples: ["#ff0000", "1", "true"] diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index cf032c2de5..e77cd531fa 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -27,12 +27,6 @@ groups: 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`. - - id: feature_flag.value - type: string - stability: experimental - examples: ["#ff0000", "1", "true"] - brief: > - The evaluated value of the feature flag. - id: feature_flag.context.id type: string stability: experimental From f12c1cfb002ad01690bb4f2f64dcb649c06e2269 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 5 Nov 2024 15:12:58 -0500 Subject: [PATCH 16/37] Add evaluation reason --- model/feature-flag/logs.yaml | 2 ++ model/feature-flag/registry.yaml | 43 ++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 7ae9efdce8..0126d9d24a 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -25,6 +25,8 @@ groups: requirement_level: recommended - ref: feature_flag.set.id requirement_level: recommended + - ref: feature_flag.reason + requirement_level: recommended body: id: feature_flag.evaluation type: map diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index e77cd531fa..264db41599 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -45,3 +45,46 @@ groups: examples: ["proj-1", "ab98sgs", "service1/dev"] brief: > The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. + - id: feature_flag.reason + type: + members: + - id: static + value: "static" + brief: The resolved value is static (no dynamic evaluation). + stability: experimental + - 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: experimental + - 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: experimental + - id: split + value: "split" + brief: The resolved value was the result of pseudorandom assignment. + stability: experimental + - id: cached + value: "cached" + brief: The resolved value was retrieved from cache. + stability: experimental + - id: disabled + value: "disabled" + brief: The resolved value was the result of the flag being disabled in the management system. + stability: experimental + - id: unknown + value: "unknown" + brief: The reason for the resolved value could not be determined. + stability: experimental + - id: stale + value: "stale" + brief: The resolved value is non-authoritative or possibly out of date + stability: experimental + - id: error + value: "error" + brief: The resolved value was the result of an error. + stability: experimental + stability: experimental + examples: ["static", "targeting_match", "error", "default"] + brief: > + The reason code which shows how a feature flag value was determined. From 7555d8610fe2d9527a2e59462e9790dae983cd34 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 5 Nov 2024 15:13:35 -0500 Subject: [PATCH 17/37] Generate tables --- docs/attributes-registry/feature-flag.md | 20 +++++++++++-- docs/feature-flags/feature-flags-logs.md | 38 ++++++++++++++++++------ 2 files changed, 46 insertions(+), 12 deletions(-) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index fa98e30bed..3d4efd85cf 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -16,10 +16,10 @@ 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.flag_set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.provider.id` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.value` | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.system` | string | Identifies the feature flag provider. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.variant` | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -28,6 +28,20 @@ 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.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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `default` | The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disabled` | The resolved value was the result of the flag being disabled in the management system. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `error` | The resolved value was the result of an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `split` | The resolved value was the result of pseudorandom assignment. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stale` | The resolved value is non-authoritative or possibly out of date | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `static` | The resolved value is static (no dynamic evaluation). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unknown` | The reason for the resolved value could not be determined. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + ## Deprecated Feature Flag Attributes Describes deprecated Feature Flag attributes. diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 20bc944e95..eca50053b5 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -48,26 +48,46 @@ The table below indicates which attributes should be added to the The event name MUST be `feature_flag.evaluation`. -This semantic convention defines the attributes used to represent a feature flag evaluation as an event. +This semantic convention defines the attributes used to represent a feature flag evaluation as an event. A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag value is evaluated, which may happen many times over the course of an application lifecycle. For example, a website A/B testing different animations may evaluate a flag each time a button is clicked. A `feature_flag.evaluation` event is emitted on each evaluation even if the result is the same. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.value`](/docs/attributes-registry/feature-flag.md) | string | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [2] | `red`; `true`; `on` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.flag_set.id`](/docs/attributes-registry/feature-flag.md) | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.provider.id`](/docs/attributes-registry/feature-flag.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.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` | ![Experimental](https://img.shields.io/badge/-experimental-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) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `feature_flag.value` should be treated as opt-in. - -**[2]:** A semantic identifier, commonly referred to as a variant, provides a means +**[1]:** 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`. -**[3]:** If feature flag provider supplies a variant or equivalent concept. +**[2]:** If feature flag provider supplies a variant or equivalent concept. + +`feature_flag.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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `default` | The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `disabled` | The resolved value was the result of the flag being disabled in the management system. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `error` | The resolved value was the result of an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `split` | The resolved value was the result of pseudorandom assignment. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stale` | The resolved value is non-authoritative or possibly out of date | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `static` | The resolved value is static (no dynamic evaluation). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `unknown` | The reason for the resolved value could not be determined. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**Body fields:** + +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `value` | undefined | The evaluated value of the feature flag. | `#ff0000`; `1`; `true` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `value` should be treated as opt-in. From 9ef0ba1d701ea07a3e1162fa7de1796f322d94ac Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 5 Nov 2024 15:41:36 -0500 Subject: [PATCH 18/37] Add feature flag error code --- docs/attributes-registry/feature-flag.md | 14 +++++++++ docs/feature-flags/feature-flags-logs.md | 14 +++++++++ model/feature-flag/logs.yaml | 3 ++ model/feature-flag/registry.yaml | 39 ++++++++++++++++++++++++ 4 files changed, 70 insertions(+) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 3d4efd85cf..764d4c8fc4 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -16,6 +16,7 @@ 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.error.code` | string | An error code which shows why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -28,6 +29,19 @@ 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.error.code` 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 | +|---|---|---| +| `flag_not_found` | The flag could not be found. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `invalid_context` | The evaluation context does not meet provider requirements. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `provider_fatal` | The provider has entered an irrecoverable error state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `provider_not_ready` | The value was resolved before the provider was initialized. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + `feature_flag.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 eca50053b5..fe19c4eae9 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -53,6 +53,7 @@ This semantic convention defines the attributes used to represent a feature flag | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.error.code`](/docs/attributes-registry/feature-flag.md) | string | An error code which shows why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` If an error occurred during flag evaluation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -67,6 +68,19 @@ For example, the variant `red` maybe be used for the value `#c05543`. **[2]:** If feature flag provider supplies a variant or equivalent concept. +`feature_flag.error.code` 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 | +|---|---|---| +| `flag_not_found` | The flag could not be found. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `invalid_context` | The evaluation context does not meet provider requirements. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `provider_fatal` | The provider has entered an irrecoverable error state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `provider_not_ready` | The value was resolved before the provider was initialized. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + `feature_flag.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-flag/logs.yaml b/model/feature-flag/logs.yaml index 0126d9d24a..ca01462c8e 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -27,6 +27,9 @@ groups: requirement_level: recommended - ref: feature_flag.reason requirement_level: recommended + - ref: feature_flag.error.code + requirement_level: + conditionally_required: If an error occurred during flag evaluation. body: id: feature_flag.evaluation type: map diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 264db41599..eec560079a 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -88,3 +88,42 @@ groups: examples: ["static", "targeting_match", "error", "default"] brief: > The reason code which shows how a feature flag value was determined. + - id: feature_flag.error.code + type: + members: + - id: provider_not_ready + value: "provider_not_ready" + brief: The value was resolved before the provider was initialized. + stability: experimental + - id: flag_not_found + value: "flag_not_found" + brief: The flag could not be found. + stability: experimental + - id: parse_error + value: "parse_error" + brief: An error was encountered parsing data, such as a flag configuration. + stability: experimental + - id: type_mismatch + value: "type_mismatch" + brief: The type of the flag value does not match the expected type. + stability: experimental + - id: targeting_key_missing + value: "targeting_key_missing" + brief: The provider requires a targeting key and one was not provided in the evaluation context. + stability: experimental + - id: invalid_context + value: "invalid_context" + brief: The evaluation context does not meet provider requirements. + stability: experimental + - id: provider_fatal + value: "provider_fatal" + brief: The provider has entered an irrecoverable error state. + stability: experimental + - id: general + value: "general" + brief: The error was for a reason not enumerated above. + stability: experimental + stability: experimental + examples: ["provider_not_ready", "targeting_key_missing", "provider_fatal", "general"] + brief: > + An error code which shows why a flag evaluation failed From ebab494c97d3a6cbf184ad44a58e2928dbf6722a Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 5 Nov 2024 15:44:33 -0500 Subject: [PATCH 19/37] Add feature flag evaluation log motivation --- docs/feature-flags/feature-flags-logs.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index fe19c4eae9..6727661305 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -14,9 +14,15 @@ such as when the application loads or on a timer. To record a flag evaluation as a part of a transaction context, consider [recording it as a span event](feature-flags-spans.md). -For more information about why it is useful to capture feature flag evaluations, -refer to the [motivation](feature-flags-spans.md#motivation) -section of the trace semantic convention for feature flag evaluations. +## Motivation + +Features flags are commonly used in modern applications to decouple feature releases from deployments. +Many feature flagging tools support the ability to update flag configurations in near real-time from a remote feature flag management service. +They also commonly allow rulesets to be defined that return values based on contextual information. +For example, a feature could be enabled only for a specific subset of users based on context (e.g. users email domain, membership tier, country). + +Since feature flags are dynamic and affect runtime behavior, it's important to collect relevant feature flag telemetry signals. +This can be used to determine the impact a feature has on a request, enabling enhanced observability use cases, such as A/B testing or progressive feature releases. From fcca5a6512df049869f68433fbde83bbbb70a779 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 5 Nov 2024 15:46:20 -0500 Subject: [PATCH 20/37] Fix: provider.id renamed to system --- docs/attributes-registry/feature-flag.md | 2 +- model/feature-flag/deprecated/registry-deprecated.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 764d4c8fc4..5ceda42855 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -62,4 +62,4 @@ Describes deprecated Feature Flag attributes. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `feature_flag.provider_name` | string | Deprecated, use `feature_flag.provider.id` instead. | `Flag Manager` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.provider.id`. | +| `feature_flag.provider_name` | string | Deprecated, use `feature_flag.system` instead. | `Flag Manager` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `feature_flag.system`. | diff --git a/model/feature-flag/deprecated/registry-deprecated.yaml b/model/feature-flag/deprecated/registry-deprecated.yaml index 7b4c33e763..2f3a681454 100644 --- a/model/feature-flag/deprecated/registry-deprecated.yaml +++ b/model/feature-flag/deprecated/registry-deprecated.yaml @@ -6,7 +6,7 @@ groups: attributes: - id: feature_flag.provider_name type: string - brief: 'Deprecated, use `feature_flag.provider.id` instead.' + brief: 'Deprecated, use `feature_flag.system` instead.' stability: experimental - deprecated: "Replaced by `feature_flag.provider.id`." + deprecated: "Replaced by `feature_flag.system`." examples: ["Flag Manager"] From 5513c8120bd187388ade2b0039830343bde61fdd Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 5 Nov 2024 16:00:09 -0500 Subject: [PATCH 21/37] Add flag evaluation error message --- docs/attributes-registry/feature-flag.md | 1 + docs/feature-flags/feature-flags-logs.md | 13 +++++++++---- model/feature-flag/logs.yaml | 5 ++++- model/feature-flag/registry.yaml | 5 +++++ 4 files changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 5ceda42855..445bc6f041 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -17,6 +17,7 @@ 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.error.code` | string | An error code which shows why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.error.message` | string | A message explaining why an error occurred during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 6727661305..422ac6c269 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -59,20 +59,25 @@ This semantic convention defines the attributes used to represent a feature flag | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.error.code`](/docs/attributes-registry/feature-flag.md) | string | An error code which shows why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` If an error occurred during flag evaluation. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.error.code`](/docs/attributes-registry/feature-flag.md) | string | An error code which shows why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.error.message`](/docs/attributes-registry/feature-flag.md) | string | A message explaining why an error occurred during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.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` | ![Experimental](https://img.shields.io/badge/-experimental-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) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** A semantic identifier, commonly referred to as a variant, provides a means +**[1]:** Required if an error occured during flag evaluation and `feature_flag.error.message` is not set, recommended otherwise. + +**[2]:** Required if an error occured during flag evaluation and `feature_flag.error.code` is not set, recommended otherwise. + +**[3]:** 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`. -**[2]:** If feature flag provider supplies a variant or equivalent concept. +**[4]:** If feature flag provider supplies a variant or equivalent concept. `feature_flag.error.code` 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. diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index ca01462c8e..cfd9c7ca20 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -29,7 +29,10 @@ groups: requirement_level: recommended - ref: feature_flag.error.code requirement_level: - conditionally_required: If an error occurred during flag evaluation. + conditionally_required: Required if an error occured during flag evaluation and `feature_flag.error.message` is not set, recommended otherwise. + - ref: feature_flag.error.message + requirement_level: + conditionally_required: Required if an error occured during flag evaluation and `feature_flag.error.code` is not set, recommended otherwise. body: id: feature_flag.evaluation type: map diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index eec560079a..7481c51499 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -127,3 +127,8 @@ groups: examples: ["provider_not_ready", "targeting_key_missing", "provider_fatal", "general"] brief: > An error code which shows why a flag evaluation failed + - id: feature_flag.error.message + type: string + stability: experimental + examples: ["Flag `header-color` expected type `string` but found type `number`"] + brief: A message explaining why an error occurred during flag evaluation. From 27aa56a98050a0352b7c098de1816d34fad90afe Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 6 Nov 2024 08:53:48 -0500 Subject: [PATCH 22/37] Misspell --- docs/feature-flags/README.md | 1 - docs/feature-flags/feature-flags-logs.md | 4 ++-- model/feature-flag/logs.yaml | 4 ++-- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/feature-flags/README.md b/docs/feature-flags/README.md index 2262031198..1d4a454078 100644 --- a/docs/feature-flags/README.md +++ b/docs/feature-flags/README.md @@ -14,7 +14,6 @@ evaluations in spans and logs. Semantic conventions for feature flags are defined for the following signals: -* [Feature Flags in Spans](feature-flags-spans.md): Semantic Conventions for recording feature flags in *spans*. * [Feature Flags in Logs](feature-flags-logs.md): Semantic Conventions for recording feature flags in *logs*. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 422ac6c269..7c972f53b0 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -68,9 +68,9 @@ This semantic convention defines the attributes used to represent a feature flag | [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Required if an error occured during flag evaluation and `feature_flag.error.message` is not set, recommended otherwise. +**[1]:** Required if an error occurred during flag evaluation and `feature_flag.error.message` is not set, recommended otherwise. -**[2]:** Required if an error occured during flag evaluation and `feature_flag.error.code` is not set, recommended otherwise. +**[2]:** Required if an error occurred during flag evaluation and `feature_flag.error.code` is not set, recommended otherwise. **[3]:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index cfd9c7ca20..49d83d1936 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -29,10 +29,10 @@ groups: requirement_level: recommended - ref: feature_flag.error.code requirement_level: - conditionally_required: Required if an error occured during flag evaluation and `feature_flag.error.message` is not set, recommended otherwise. + conditionally_required: Required if an error occurred during flag evaluation and `feature_flag.error.message` is not set, recommended otherwise. - ref: feature_flag.error.message requirement_level: - conditionally_required: Required if an error occured during flag evaluation and `feature_flag.error.code` is not set, recommended otherwise. + conditionally_required: Required if an error occurred during flag evaluation and `feature_flag.error.code` is not set, recommended otherwise. body: id: feature_flag.evaluation type: map From 5ae514a3353767ebb9017917245efcfbdcebc3de Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 6 Nov 2024 14:48:20 -0500 Subject: [PATCH 23/37] Apply suggestions from code review and remove broken links --- docs/attributes-registry/feature-flag.md | 12 ++++++------ docs/feature-flags/feature-flags-logs.md | 18 ++++++++---------- docs/general/trace.md | 1 - model/feature-flag/logs.yaml | 10 +++++----- model/feature-flag/registry.yaml | 12 ++++++------ 5 files changed, 25 insertions(+), 28 deletions(-) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 445bc6f041..1f058e9eff 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -16,11 +16,11 @@ 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.error.code` | string | An error code which shows why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.error.message` | string | A message explaining why an error occurred during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.evaluation.error.code` | string | An error code which denotes why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | ![Experimental](https://img.shields.io/badge/-experimental-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`` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `feature_flag.evaluation.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.system` | string | Identifies the feature flag provider. | `Flag Manager` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.variant` | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -30,7 +30,7 @@ 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.error.code` 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.evaluation.error.code` 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 | |---|---|---| @@ -43,7 +43,7 @@ For example, the variant `red` maybe be used for the value `#c05543`. | `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`feature_flag.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.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 | |---|---|---| diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 7c972f53b0..9dcecba10b 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -11,8 +11,6 @@ a [log record](https://github.com/open-telemetry/opentelemetry-specification/tre [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/bridge-api.md#emit-a-logrecord). This is useful when a flag is evaluated outside of a transaction context such as when the application loads or on a timer. -To record a flag evaluation as a part of a transaction context, -consider [recording it as a span event](feature-flags-spans.md). ## Motivation @@ -59,18 +57,18 @@ This semantic convention defines the attributes used to represent a feature flag | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.error.code`](/docs/attributes-registry/feature-flag.md) | string | An error code which shows why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.error.message`](/docs/attributes-registry/feature-flag.md) | string | A message explaining why an error occurred during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.evaluation.error.code`](/docs/attributes-registry/feature-flag.md) | string | An error code which denotes why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-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`` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.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` | ![Experimental](https://img.shields.io/badge/-experimental-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) which the feature flag belongs to in a flag management system. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Required if an error occurred during flag evaluation and `feature_flag.error.message` is not set, recommended otherwise. +**[1]:** Required if an error occurred during flag evaluation and `feature_flag.evaluation.error.message` is not set, recommended otherwise. -**[2]:** Required if an error occurred during flag evaluation and `feature_flag.error.code` is not set, recommended otherwise. +**[2]:** Required if an error occurred during flag evaluation and `feature_flag.evaluation.error.code` is not set, recommended otherwise. **[3]:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can @@ -79,7 +77,7 @@ For example, the variant `red` maybe be used for the value `#c05543`. **[4]:** If feature flag provider supplies a variant or equivalent concept. -`feature_flag.error.code` 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.evaluation.error.code` 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 | |---|---|---| @@ -92,7 +90,7 @@ For example, the variant `red` maybe be used for the value `#c05543`. | `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`feature_flag.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.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 | |---|---|---| diff --git a/docs/general/trace.md b/docs/general/trace.md index 09b164af16..565913a31b 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -27,7 +27,6 @@ The following semantic conventions for spans are defined: * [Database](/docs/database/database-spans.md): For SQL and NoSQL client call spans. * [Exceptions](/docs/exceptions/exceptions-spans.md): For recording exceptions associated with a span. * [FaaS](/docs/faas/faas-spans.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. -* [Feature Flags](/docs/feature-flags/feature-flags-spans.md): For recording feature flag evaluations associated with a span. * [HTTP](/docs/http/http-spans.md): For HTTP client and server spans. * [Messaging](/docs/messaging/messaging-spans.md): For messaging systems (queues, publish/subscribe, etc.) spans. * [Object Stores](/docs/object-stores/README.md): Semantic Conventions for object stores spans. diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 49d83d1936..9fdc402e24 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -25,14 +25,14 @@ groups: requirement_level: recommended - ref: feature_flag.set.id requirement_level: recommended - - ref: feature_flag.reason + - ref: feature_flag.evaluation.reason requirement_level: recommended - - ref: feature_flag.error.code + - ref: feature_flag.evaluation.error.code requirement_level: - conditionally_required: Required if an error occurred during flag evaluation and `feature_flag.error.message` is not set, recommended otherwise. - - ref: feature_flag.error.message + conditionally_required: Required if an error occurred during flag evaluation and `feature_flag.evaluation.error.message` is not set, recommended otherwise. + - ref: feature_flag.evaluation.error.message requirement_level: - conditionally_required: Required if an error occurred during flag evaluation and `feature_flag.error.code` is not set, recommended otherwise. + conditionally_required: Required if an error occurred during flag evaluation and `feature_flag.evaluation.error.code` is not set, recommended otherwise. body: id: feature_flag.evaluation type: map diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 7481c51499..63b6f48803 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -44,8 +44,8 @@ groups: stability: experimental examples: ["proj-1", "ab98sgs", "service1/dev"] brief: > - The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) which the feature flag belongs to in a flag management system. - - id: feature_flag.reason + The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. + - id: feature_flag.evaluation.reason type: members: - id: static @@ -88,7 +88,7 @@ groups: examples: ["static", "targeting_match", "error", "default"] brief: > The reason code which shows how a feature flag value was determined. - - id: feature_flag.error.code + - id: feature_flag.evaluation.error.code type: members: - id: provider_not_ready @@ -126,9 +126,9 @@ groups: stability: experimental examples: ["provider_not_ready", "targeting_key_missing", "provider_fatal", "general"] brief: > - An error code which shows why a flag evaluation failed - - id: feature_flag.error.message + An error code which denotes why a flag evaluation failed + - id: feature_flag.evaluation.error.message type: string stability: experimental examples: ["Flag `header-color` expected type `string` but found type `number`"] - brief: A message explaining why an error occurred during flag evaluation. + brief: A message explaining the nature of an error occurring during flag evaluation. From 118ce57bcbb789947ac7db1d19b3108fea97f34e Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 6 Nov 2024 14:55:24 -0500 Subject: [PATCH 24/37] Fix issue number --- .chloggen/{1140.yaml => 1440.yaml} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename .chloggen/{1140.yaml => 1440.yaml} (86%) diff --git a/.chloggen/1140.yaml b/.chloggen/1440.yaml similarity index 86% rename from .chloggen/1140.yaml rename to .chloggen/1440.yaml index bfb24de677..1b932ffad4 100644 --- a/.chloggen/1140.yaml +++ b/.chloggen/1440.yaml @@ -1,4 +1,4 @@ change_type: enhancement component: feature_flag note: Define `feature_flag.evaluation` event. -issues: [1140] +issues: [1440] From 37d9b8e92c521979ba30843058bdf9b66a9fb303 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 11 Nov 2024 16:16:07 -0700 Subject: [PATCH 25/37] Apply suggestions from code review --- docs/feature-flags/feature-flags-logs.md | 18 ++++++++++-------- model/feature-flag/logs.yaml | 8 ++++---- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index faa032607d..d64be1250d 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -53,30 +53,32 @@ The table below indicates which attributes should be added to the The event name MUST be `feature_flag.evaluation`. -This semantic convention defines the attributes used to represent a feature flag evaluation as an event. A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag value is evaluated, which may happen many times over the course of an application lifecycle. For example, a website A/B testing different animations may evaluate a flag each time a button is clicked. A `feature_flag.evaluation` event is emitted on each evaluation even if the result is the same. +Defines feature flag evaluation as an event. + +A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag value is evaluated, which may happen many times over the course of an application lifecycle. For example, a website A/B testing different animations may evaluate a flag each time a button is clicked. A `feature_flag.evaluation` event is emitted on each evaluation even if the result is the same. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.evaluation.error.code`](/docs/attributes-registry/feature-flag.md) | string | An error code which denotes why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-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`` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [2] | `red`; `true`; `on` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-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` [4] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Required if an error occurred during flag evaluation and `feature_flag.evaluation.error.message` is not set, recommended otherwise. - -**[2]:** Required if an error occurred during flag evaluation and `feature_flag.evaluation.error.code` is not set, recommended otherwise. +**[1]:** if and only if an error occurred during flag evaluation. -**[3]:** A semantic identifier, commonly referred to as a variant, provides a means +**[2]:** 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]:** If feature flag provider supplies a variant or equivalent concept. +**[3]:** If feature flag provider supplies a variant or equivalent concept. + +**[4]:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `feature_flag.evaluation.error.code` in `feature_flag.evaluation.error.message`. `feature_flag.evaluation.error.code` 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. diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 9fdc402e24..7e1361f750 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -3,8 +3,8 @@ groups: type: event name: feature_flag.evaluation brief: > - This semantic convention defines the attributes used to represent a - feature flag evaluation as an event. + Defines feature flag evaluation as an event. + note: > A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag value is evaluated, which may happen many times over the course of an application lifecycle. @@ -29,10 +29,10 @@ groups: requirement_level: recommended - ref: feature_flag.evaluation.error.code requirement_level: - conditionally_required: Required if an error occurred during flag evaluation and `feature_flag.evaluation.error.message` is not set, recommended otherwise. + conditionally_required: if and only if an error occurred during flag evaluation. - ref: feature_flag.evaluation.error.message requirement_level: - conditionally_required: Required if an error occurred during flag evaluation and `feature_flag.evaluation.error.code` is not set, recommended otherwise. + recommended: If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `feature_flag.evaluation.error.code` in `feature_flag.evaluation.error.message`. body: id: feature_flag.evaluation type: map From 31eb9c62be86f50c68ad3e0b47a86a11dbb307b0 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 11 Nov 2024 16:20:48 -0700 Subject: [PATCH 26/37] Use generic error.type --- docs/feature-flags/feature-flags-logs.md | 36 +++++++++++++--------- model/feature-flag/logs.yaml | 18 +++++++++-- model/feature-flag/registry.yaml | 39 ------------------------ 3 files changed, 37 insertions(+), 56 deletions(-) diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index d64be1250d..0752024198 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -60,27 +60,16 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.evaluation.error.code`](/docs/attributes-registry/feature-flag.md) | string | An error code which denotes why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [2] | `red`; `true`; `on` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `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] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-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` [4] | ![Experimental](https://img.shields.io/badge/-experimental-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] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** if and only if an error occurred during flag evaluation. - -**[2]:** 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`. - -**[3]:** If feature flag provider supplies a variant or equivalent concept. - -**[4]:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `feature_flag.evaluation.error.code` in `feature_flag.evaluation.error.message`. - -`feature_flag.evaluation.error.code` 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. +**[1]:** `feature_flag.evaluation.error.code` 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 | |---|---|---| @@ -93,6 +82,23 @@ For example, the variant `red` maybe be used for the value `#c05543`. | `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +**[2]:** If and only if an error occurred during flag evaluation. + +**[3]:** 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]:** If feature flag provider supplies a variant or equivalent concept. + +**[5]:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `feature_flag.evaluation.error.code` in `feature_flag.evaluation.error.message`. + +`error.type` 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 | +|---|---|---| +| `_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) | + `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 | diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 7e1361f750..9bb33cd749 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -27,9 +27,23 @@ groups: requirement_level: recommended - ref: feature_flag.evaluation.reason requirement_level: recommended - - ref: feature_flag.evaluation.error.code + - ref: error.type requirement_level: - conditionally_required: if and only if an error occurred during flag evaluation. + conditionally_required: If and only if an error occurred during flag evaluation. + # TODO: move note to yaml once https://github.com/open-telemetry/build-tools/issues/192 is supported + note: | + `feature_flag.evaluation.error.code` 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 | + |---|---|---| + | `flag_not_found` | The flag could not be found. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `invalid_context` | The evaluation context does not meet provider requirements. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `provider_fatal` | The provider has entered an irrecoverable error state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `provider_not_ready` | The value was resolved before the provider was initialized. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ref: feature_flag.evaluation.error.message requirement_level: recommended: If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `feature_flag.evaluation.error.code` in `feature_flag.evaluation.error.message`. diff --git a/model/feature-flag/registry.yaml b/model/feature-flag/registry.yaml index 63b6f48803..76b1d5fe3c 100644 --- a/model/feature-flag/registry.yaml +++ b/model/feature-flag/registry.yaml @@ -88,45 +88,6 @@ 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.code - type: - members: - - id: provider_not_ready - value: "provider_not_ready" - brief: The value was resolved before the provider was initialized. - stability: experimental - - id: flag_not_found - value: "flag_not_found" - brief: The flag could not be found. - stability: experimental - - id: parse_error - value: "parse_error" - brief: An error was encountered parsing data, such as a flag configuration. - stability: experimental - - id: type_mismatch - value: "type_mismatch" - brief: The type of the flag value does not match the expected type. - stability: experimental - - id: targeting_key_missing - value: "targeting_key_missing" - brief: The provider requires a targeting key and one was not provided in the evaluation context. - stability: experimental - - id: invalid_context - value: "invalid_context" - brief: The evaluation context does not meet provider requirements. - stability: experimental - - id: provider_fatal - value: "provider_fatal" - brief: The provider has entered an irrecoverable error state. - stability: experimental - - id: general - value: "general" - brief: The error was for a reason not enumerated above. - stability: experimental - stability: experimental - examples: ["provider_not_ready", "targeting_key_missing", "provider_fatal", "general"] - brief: > - An error code which denotes why a flag evaluation failed - id: feature_flag.evaluation.error.message type: string stability: experimental From c08b2e237ef4152b0528552a2c253a96c4de8687 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 11 Nov 2024 16:22:55 -0700 Subject: [PATCH 27/37] Remove merge marker --- docs/feature-flags/feature-flags-logs.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 0752024198..9fb98e2dbf 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -41,7 +41,6 @@ context. The table below indicates which attributes should be added to the [LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. -<<<<<<< HEAD From c6a6587550b1ddb6f0f713b2ff14988e92227222 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 11 Nov 2024 16:26:28 -0700 Subject: [PATCH 28/37] Fix reference to error.type --- docs/attributes-registry/feature-flag.md | 14 -------------- docs/feature-flags/feature-flags-logs.md | 2 +- model/feature-flag/logs.yaml | 2 +- 3 files changed, 2 insertions(+), 16 deletions(-) diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 1f058e9eff..de4cd52d50 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -16,7 +16,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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `feature_flag.evaluation.error.code` | string | An error code which denotes why a flag evaluation failed | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | ![Experimental](https://img.shields.io/badge/-experimental-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`` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.evaluation.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -30,19 +29,6 @@ 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.error.code` 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 | -|---|---|---| -| `flag_not_found` | The flag could not be found. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `invalid_context` | The evaluation context does not meet provider requirements. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `provider_fatal` | The provider has entered an irrecoverable error state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `provider_not_ready` | The value was resolved before the provider was initialized. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - `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 | diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 9fb98e2dbf..ce12140bc9 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -68,7 +68,7 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu | [`feature_flag.system`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** `feature_flag.evaluation.error.code` 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. +**[1]:** If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 9bb33cd749..463530c8fe 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -32,7 +32,7 @@ groups: conditionally_required: If and only if an error occurred during flag evaluation. # TODO: move note to yaml once https://github.com/open-telemetry/build-tools/issues/192 is supported note: | - `feature_flag.evaluation.error.code` 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. + If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| From 43cdfd4a7e234a817162a92dfd37c3af68c9d79e Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Nov 2024 13:33:15 -0700 Subject: [PATCH 29/37] Fix event ID --- docs/feature-flags/feature-flags-logs.md | 2 +- model/feature-flag/logs.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index ce12140bc9..239580f25e 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -41,7 +41,7 @@ context. The table below indicates which attributes should be added to the [LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. - + diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 463530c8fe..e00e1efae0 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -1,5 +1,5 @@ groups: - - id: feature_flag.evaluation + - id: event.feature_flag.evaluation type: event name: feature_flag.evaluation brief: > From 091811e05f1b66cf74fa055205905f93e022eeea Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Nov 2024 13:33:34 -0700 Subject: [PATCH 30/37] Use ff specific examples for error type --- docs/feature-flags/feature-flags-logs.md | 2 +- model/feature-flag/logs.yaml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 239580f25e..8825799616 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -59,7 +59,7 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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] | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-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] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index e00e1efae0..e4f138952c 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -28,6 +28,7 @@ groups: - ref: feature_flag.evaluation.reason requirement_level: recommended - ref: error.type + examples: ["provider_not_ready", "targeting_key_missing", "provider_fatal", "general"] requirement_level: conditionally_required: If and only if an error occurred during flag evaluation. # TODO: move note to yaml once https://github.com/open-telemetry/build-tools/issues/192 is supported From d7106533b21150142babe5038815f5feadf1e61c Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Nov 2024 13:36:06 -0700 Subject: [PATCH 31/37] Fix reference to error type --- docs/feature-flags/feature-flags-logs.md | 2 +- model/feature-flag/logs.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 8825799616..02a8c73800 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -90,7 +90,7 @@ For example, the variant `red` maybe be used for the value `#c05543`. **[4]:** If feature flag provider supplies a variant or equivalent concept. -**[5]:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `feature_flag.evaluation.error.code` in `feature_flag.evaluation.error.message`. +**[5]:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`. `error.type` 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. diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index e4f138952c..4668acf248 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -47,7 +47,7 @@ groups: | `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ref: feature_flag.evaluation.error.message requirement_level: - recommended: If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `feature_flag.evaluation.error.code` in `feature_flag.evaluation.error.message`. + 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`. body: id: feature_flag.evaluation type: map From 2c5b57f0a90efdd913b5920fd430602e8adcd824 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Nov 2024 13:38:40 -0700 Subject: [PATCH 32/37] Move general to end of table --- docs/feature-flags/feature-flags-logs.md | 2 +- model/feature-flag/logs.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 02a8c73800..85964d8181 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -73,13 +73,13 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu | Value | Description | Stability | |---|---|---| | `flag_not_found` | The flag could not be found. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `invalid_context` | The evaluation context does not meet provider requirements. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `provider_fatal` | The provider has entered an irrecoverable error state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `provider_not_ready` | The value was resolved before the provider was initialized. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[2]:** If and only if an error occurred during flag evaluation. diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 4668acf248..4aae6cf22c 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -38,13 +38,13 @@ groups: | Value | Description | Stability | |---|---|---| | `flag_not_found` | The flag could not be found. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - | `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `invalid_context` | The evaluation context does not meet provider requirements. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `provider_fatal` | The provider has entered an irrecoverable error state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `provider_not_ready` | The value was resolved before the provider was initialized. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `type_mismatch` | The type of the flag value does not match the expected type. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + | `general` | The error was for a reason not enumerated above. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ref: feature_flag.evaluation.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`. From 0ef7ef2a2f49f6b36f53bebcc78708e71e6c99f1 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Nov 2024 14:07:04 -0700 Subject: [PATCH 33/37] Trim trailing whitespace --- model/feature-flag/logs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/feature-flag/logs.yaml b/model/feature-flag/logs.yaml index 4aae6cf22c..0de7c95577 100644 --- a/model/feature-flag/logs.yaml +++ b/model/feature-flag/logs.yaml @@ -3,7 +3,7 @@ groups: type: event name: feature_flag.evaluation brief: > - Defines feature flag evaluation as an event. + Defines feature flag evaluation as an event. note: > A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag value is evaluated, which may happen many times over the course of an From 6de17ec86079fedf8eb0a4cecc1dd792721ad349 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 13 Nov 2024 11:08:19 -0700 Subject: [PATCH 34/37] Rename feature_flag.provider_name to feature_flag.system in schema --- schema-next.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/schema-next.yaml b/schema-next.yaml index 5439843483..50afab2b96 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -16,6 +16,11 @@ versions: vcs.repository.ref.name: vcs.ref.head.name vcs.repository.ref.revision: vcs.ref.head.revision vcs.repository.ref.type: vcs.ref.head.type + # https://github.com/open-telemetry/semantic-conventions/pull/1440 + - rename_attributes: + attribute_map: + feature_flag.provider_name: feature_flag.system + metrics: changes: # https://github.com/open-telemetry/semantic-conventions/pull/1492 From a1b54b659820078be5b43dfbe61540817e0257a3 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 13 Nov 2024 14:03:28 -0700 Subject: [PATCH 35/37] Apply suggestions from code review Co-authored-by: Liudmila Molkova --- .chloggen/1440.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.chloggen/1440.yaml b/.chloggen/1440.yaml index 1b932ffad4..cf1f14951d 100644 --- a/.chloggen/1440.yaml +++ b/.chloggen/1440.yaml @@ -1,4 +1,4 @@ -change_type: enhancement +change_type: breaking component: feature_flag -note: Define `feature_flag.evaluation` event. +note: Rename `feature_flag` event to `feature_flag.evaluation` event, define new feature flag attributes and provide body definition. Remove `feature_flag` span event definition in favor of log-based event. issues: [1440] From 4548c485d5cc774446e8714784f275f9c35fc6b0 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Thu, 14 Nov 2024 10:47:23 -0700 Subject: [PATCH 36/37] Yaml lint --- .chloggen/1440.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.chloggen/1440.yaml b/.chloggen/1440.yaml index cf1f14951d..5a75502e7e 100644 --- a/.chloggen/1440.yaml +++ b/.chloggen/1440.yaml @@ -1,4 +1,6 @@ change_type: breaking component: feature_flag -note: Rename `feature_flag` event to `feature_flag.evaluation` event, define new feature flag attributes and provide body definition. Remove `feature_flag` span event definition in favor of log-based event. +note: > + Rename `feature_flag` event to `feature_flag.evaluation` event, define new feature flag attributes and provide body definition. + Remove `feature_flag` span event definition in favor of log-based event. issues: [1440] From 753c69b5e8496eea3c59e0dfca222de3f0a83d2b Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Thu, 14 Nov 2024 12:13:18 -0700 Subject: [PATCH 37/37] Trailing space --- .chloggen/1440.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/1440.yaml b/.chloggen/1440.yaml index 5a75502e7e..f130197287 100644 --- a/.chloggen/1440.yaml +++ b/.chloggen/1440.yaml @@ -2,5 +2,5 @@ change_type: breaking component: feature_flag note: > Rename `feature_flag` event to `feature_flag.evaluation` event, define new feature flag attributes and provide body definition. - Remove `feature_flag` span event definition in favor of log-based event. + Remove `feature_flag` span event definition in favor of log-based event. issues: [1440]