diff --git a/.chloggen/ff-value-body-attribute.yaml b/.chloggen/ff-value-body-attribute.yaml new file mode 100755 index 0000000000..3314b576c6 --- /dev/null +++ b/.chloggen/ff-value-body-attribute.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: feature_flag + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Move the evaluated value from the event body to attributes + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1990] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/feature-flag.md b/docs/attributes-registry/feature-flag.md index 803cb30796..7ee30b6f17 100644 --- a/docs/attributes-registry/feature-flag.md +++ b/docs/attributes-registry/feature-flag.md @@ -14,11 +14,19 @@ This document defines attributes for Feature Flags. | `feature_flag.evaluation.reason` | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | ![Development](https://img.shields.io/badge/-development-blue) | | `feature_flag.key` | string | The lookup key of the feature flag. | `logo-color` | ![Development](https://img.shields.io/badge/-development-blue) | | `feature_flag.provider_name` | string | Identifies the feature flag provider. | `Flag Manager` | ![Development](https://img.shields.io/badge/-development-blue) | +| `feature_flag.result.type` | string | The JSON type of the `feature_flag.result.value`. | `string`; `boolean`; `number` | ![Development](https://img.shields.io/badge/-development-blue) | +| `feature_flag.result.value` | string | The evaluated value of the feature flag represented as a JSON string. [1] | `#ff0000`; `1`; `true` | ![Development](https://img.shields.io/badge/-development-blue) | | `feature_flag.set.id` | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` | ![Development](https://img.shields.io/badge/-development-blue) | -| `feature_flag.variant` | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` | ![Development](https://img.shields.io/badge/-development-blue) | +| `feature_flag.variant` | string | A semantic identifier for an evaluated flag value. [2] | `red`; `true`; `on` | ![Development](https://img.shields.io/badge/-development-blue) | | `feature_flag.version` | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | ![Development](https://img.shields.io/badge/-development-blue) | -**[1] `feature_flag.variant`:** A semantic identifier, commonly referred to as a variant, provides a means +**[1] `feature_flag.result.value`:** With some feature flag providers, feature flag results can be quite large or contain private or sensitive details. +Because of this, `feature_flag.result.variant` is often the preferred attribute if it is available. + +It may be desirable to redact or otherwise limit the size and scope of `feature_flag.result.value` if possible. +Because the evaluated flag value is unstructured and may be any type, it left to the instrumentation author to determine how best to achieve this. + +**[2] `feature_flag.variant`:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can provide additional context for understanding the meaning behind a value. For example, the variant `red` maybe be used for the value `#c05543`. @@ -38,3 +46,15 @@ For example, the variant `red` maybe be used for the value `#c05543`. | `static` | The resolved value is static (no dynamic evaluation). | ![Development](https://img.shields.io/badge/-development-blue) | | `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Development](https://img.shields.io/badge/-development-blue) | | `unknown` | The reason for the resolved value could not be determined. | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`feature_flag.result.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 | +|---|---|---| +| `array` | The `feature_flag.result.value` is a stringified array. | ![Development](https://img.shields.io/badge/-development-blue) | +| `boolean` | The `feature_flag.result.value` is a stringified boolean. | ![Development](https://img.shields.io/badge/-development-blue) | +| `number` | The `feature_flag.result.value` is a stringified number. | ![Development](https://img.shields.io/badge/-development-blue) | +| `object` | The `feature_flag.result.value` is a stringified object. | ![Development](https://img.shields.io/badge/-development-blue) | +| `string` | The `feature_flag.result.value` is a string. | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 80b7c5525d..04c2d9c337 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -60,9 +60,11 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu |---|---|---|---|---|---| | [`feature_flag.key`](/docs/attributes-registry/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [3] | `red`; `true`; `on` | `Conditionally Required` [4] | ![Development](https://img.shields.io/badge/-development-blue) | +| [`feature_flag.result.type`](/docs/attributes-registry/feature-flag.md) | string | The JSON type of the `feature_flag.result.value`. | `string`; `boolean`; `number` | `Conditionally Required` [3] | ![Development](https://img.shields.io/badge/-development-blue) | +| [`feature_flag.result.value`](/docs/attributes-registry/feature-flag.md) | string | The evaluated value of the feature flag represented as a JSON string. [4] | `#ff0000`; `1`; `true` | `Conditionally Required` [5] | ![Development](https://img.shields.io/badge/-development-blue) | +| [`feature_flag.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [6] | `red`; `true`; `on` | `Conditionally Required` [7] | ![Development](https://img.shields.io/badge/-development-blue) | | [`feature_flag.context.id`](/docs/attributes-registry/feature-flag.md) | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`feature_flag.evaluation.error.message`](/docs/attributes-registry/feature-flag.md) | string | A message explaining the nature of an error occurring during flag evaluation. | `Flag `header-color` expected type `string` but found type `number`` | `Recommended` [5] | ![Development](https://img.shields.io/badge/-development-blue) | +| [`feature_flag.evaluation.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` [8] | ![Development](https://img.shields.io/badge/-development-blue) | | [`feature_flag.evaluation.reason`](/docs/attributes-registry/feature-flag.md) | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`feature_flag.provider_name`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`feature_flag.set.id`](/docs/attributes-registry/feature-flag.md) | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -83,14 +85,24 @@ A `feature_flag.evaluation` event SHOULD be emitted whenever a feature flag valu **[2] `error.type`:** If and only if an error occurred during flag evaluation. -**[3] `feature_flag.variant`:** A semantic identifier, commonly referred to as a variant, provides a means +**[3] `feature_flag.result.type`:** If and only if `feature_flag.result.value` is set. + +**[4] `feature_flag.result.value`:** With some feature flag providers, feature flag results can be quite large or contain private or sensitive details. +Because of this, `feature_flag.result.variant` is often the preferred attribute if it is available. + +It may be desirable to redact or otherwise limit the size and scope of `feature_flag.result.value` if possible. +Because the evaluated flag value is unstructured and may be any type, it left to the instrumentation author to determine how best to achieve this. + +**[5] `feature_flag.result.value`:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `feature_flag.result.value` should be treated as opt-in. + +**[6] `feature_flag.variant`:** A semantic identifier, commonly referred to as a variant, provides a means for referring to a value without including the value itself. This can provide additional context for understanding the meaning behind a value. For example, the variant `red` maybe be used for the value `#c05543`. -**[4] `feature_flag.variant`:** If feature flag provider supplies a variant or equivalent concept. +**[7] `feature_flag.variant`:** If feature flag provider supplies a variant or equivalent concept. -**[5] `feature_flag.evaluation.error.message`:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`. +**[8] `feature_flag.evaluation.error.message`:** If and only if an error occurred. It's NOT RECOMMENDED to duplicate the value of `error.type` in `feature_flag.evaluation.error.message`. --- @@ -116,13 +128,17 @@ For example, the variant `red` maybe be used for the value `#c05543`. | `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Development](https://img.shields.io/badge/-development-blue) | | `unknown` | The reason for the resolved value could not be determined. | ![Development](https://img.shields.io/badge/-development-blue) | -**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] | ![Development](https://img.shields.io/badge/-development-blue) | +`feature_flag.result.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. -**[1] `value`:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `value` should be treated as opt-in. +| Value | Description | Stability | +|---|---|---| +| `array` | The `feature_flag.result.value` is a stringified array. | ![Development](https://img.shields.io/badge/-development-blue) | +| `boolean` | The `feature_flag.result.value` is a stringified boolean. | ![Development](https://img.shields.io/badge/-development-blue) | +| `number` | The `feature_flag.result.value` is a stringified number. | ![Development](https://img.shields.io/badge/-development-blue) | +| `object` | The `feature_flag.result.value` is a stringified object. | ![Development](https://img.shields.io/badge/-development-blue) | +| `string` | The `feature_flag.result.value` is a string. | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/feature-flags/logs.yaml b/model/feature-flags/logs.yaml index fa5429af50..a851f1e613 100644 --- a/model/feature-flags/logs.yaml +++ b/model/feature-flags/logs.yaml @@ -18,6 +18,15 @@ groups: - ref: feature_flag.variant requirement_level: conditionally_required: If feature flag provider supplies a variant or equivalent concept. + - ref: feature_flag.result.value + requirement_level: + conditionally_required: > + If and only if feature flag provider does not supply variant or equivalent concept. + Otherwise, `feature_flag.result.value` should be treated as opt-in. + - ref: feature_flag.result.type + requirement_level: + conditionally_required: > + If and only if `feature_flag.result.value` is set. - ref: feature_flag.provider_name requirement_level: recommended - ref: feature_flag.context.id @@ -49,18 +58,3 @@ groups: - 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`. - body: - id: feature_flag.evaluation - type: map - requirement_level: recommended - stability: development - fields: - - id: value - type: undefined - stability: development - 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-flags/registry.yaml b/model/feature-flags/registry.yaml index 264d6945be..fe845211a7 100644 --- a/model/feature-flags/registry.yaml +++ b/model/feature-flags/registry.yaml @@ -93,3 +93,40 @@ groups: stability: development examples: ["Flag `header-color` expected type `string` but found type `number`"] brief: A message explaining the nature of an error occurring during flag evaluation. + - id: feature_flag.result.value + type: string + stability: development + examples: ["#ff0000", "1", "true"] + brief: The evaluated value of the feature flag represented as a JSON string. + note: | + With some feature flag providers, feature flag results can be quite large or contain private or sensitive details. + Because of this, `feature_flag.result.variant` is often the preferred attribute if it is available. + + It may be desirable to redact or otherwise limit the size and scope of `feature_flag.result.value` if possible. + Because the evaluated flag value is unstructured and may be any type, it left to the instrumentation author to determine how best to achieve this. + - id: feature_flag.result.type + type: + members: + - id: string + value: "string" + brief: The `feature_flag.result.value` is a string. + stability: development + - id: number + value: "number" + brief: The `feature_flag.result.value` is a stringified number. + stability: development + - id: boolean + value: "boolean" + brief: The `feature_flag.result.value` is a stringified boolean. + stability: development + - id: object + value: "object" + brief: The `feature_flag.result.value` is a stringified object. + stability: development + - id: array + value: "array" + brief: The `feature_flag.result.value` is a stringified array. + stability: development + stability: development + examples: ["string", "boolean", "number"] + brief: The JSON type of the `feature_flag.result.value`.