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