Move the evaluated value from the event body to attributes (#1990)
Co-authored-by: Pete Hodgson <github@thepete.net> Co-authored-by: André Silva <2493377+askpt@users.noreply.github.com>
This commit is contained in:
Daniel Dyla
GitHub
parent
a3ae88080e
commit
5eccb6fd0e
|
|
@ -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:
|
||||
|
|
@ -16,11 +16,18 @@ This document defines attributes for Feature Flags.
|
|||
| <a id="feature-flag-key" href="#feature-flag-key">`feature_flag.key`</a> | string | The lookup key of the feature flag. | `logo-color` |  |
|
||||
| <a id="feature-flag-provider-name" href="#feature-flag-provider-name">`feature_flag.provider.name`</a> | string | Identifies the feature flag provider. | `Flag Manager` |  |
|
||||
| <a id="feature-flag-result-reason" href="#feature-flag-result-reason">`feature_flag.result.reason`</a> | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` |  |
|
||||
| <a id="feature-flag-result-variant" href="#feature-flag-result-variant">`feature_flag.result.variant`</a> | string | A semantic identifier for an evaluated flag value. [1] | `red`; `true`; `on` |  |
|
||||
| <a id="feature-flag-result-value" href="#feature-flag-result-value">`feature_flag.result.value`</a> | any | The evaluated value of the feature flag. [1] | `#ff0000`; `true`; `3` |  |
|
||||
| <a id="feature-flag-result-variant" href="#feature-flag-result-variant">`feature_flag.result.variant`</a> | string | A semantic identifier for an evaluated flag value. [2] | `red`; `true`; `on` |  |
|
||||
| <a id="feature-flag-set-id" href="#feature-flag-set-id">`feature_flag.set.id`</a> | 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` |  |
|
||||
| <a id="feature-flag-version" href="#feature-flag-version">`feature_flag.version`</a> | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` |  |
|
||||
|
||||
**[1] `feature_flag.result.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 is left to the instrumentation author to determine how best to achieve this.
|
||||
|
||||
**[2] `feature_flag.result.variant`:** A semantic identifier, commonly referred to as a variant, provides a means
|
||||
for referring to a value without including the value itself. This can
|
||||
provide additional context for understanding the meaning behind a value.
|
||||
For example, the variant `red` maybe be used for the value `#c05543`.
|
||||
|
|
|
|||
|
|
@ -60,8 +60,9 @@ 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` |  |
|
||||
| [`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] |  |
|
||||
| [`feature_flag.result.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [3] | `red`; `true`; `on` | `Conditionally Required` [4] |  |
|
||||
| [`error.message`](/docs/attributes-registry/error.md) | string | A message providing more detail about an error in human-readable form. [5] | `Unexpected input type: string`; `The user has exceeded their storage quota` | `Recommended` [6] |  |
|
||||
| [`feature_flag.result.value`](/docs/attributes-registry/feature-flag.md) | any | The evaluated value of the feature flag. [3] | `#ff0000`; `true`; `3` | `Conditionally Required` [4] |  |
|
||||
| [`feature_flag.result.variant`](/docs/attributes-registry/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [5] | `red`; `true`; `on` | `Conditionally Required` [6] |  |
|
||||
| [`error.message`](/docs/attributes-registry/error.md) | string | A message providing more detail about an error in human-readable form. [7] | `Unexpected input type: string`; `The user has exceeded their storage quota` | `Recommended` [8] |  |
|
||||
| [`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` |  |
|
||||
| [`feature_flag.provider.name`](/docs/attributes-registry/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` |  |
|
||||
| [`feature_flag.result.reason`](/docs/attributes-registry/feature-flag.md) | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | `Recommended` |  |
|
||||
|
|
@ -83,16 +84,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.result.variant`:** A semantic identifier, commonly referred to as a variant, provides a means
|
||||
**[3] `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 is left to the instrumentation author to determine how best to achieve this.
|
||||
|
||||
**[4] `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.
|
||||
|
||||
**[5] `feature_flag.result.variant`:** A semantic identifier, commonly referred to as a variant, provides a means
|
||||
for referring to a value without including the value itself. This can
|
||||
provide additional context for understanding the meaning behind a value.
|
||||
For example, the variant `red` maybe be used for the value `#c05543`.
|
||||
|
||||
**[4] `feature_flag.result.variant`:** If feature flag provider supplies a variant or equivalent concept.
|
||||
**[6] `feature_flag.result.variant`:** If feature flag provider supplies a variant or equivalent concept.
|
||||
|
||||
**[5] `error.message`:** Should not simply duplicate the value of `error.type`, but should provide more context. For example, if `error.type` is `invalid_context` the `error.message` may enumerate which context keys are missing or invalid.
|
||||
**[7] `error.message`:** Should not simply duplicate the value of `error.type`, but should provide more context. For example, if `error.type` is `invalid_context` the `error.message` may enumerate which context keys are missing or invalid.
|
||||
|
||||
**[6] `error.message`:** If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error.
|
||||
**[8] `error.message`:** If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -118,18 +127,6 @@ 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. |  |
|
||||
| `unknown` | The reason for the resolved value could not be determined. |  |
|
||||
|
||||
**Body fields:**
|
||||
|
||||
:warning: Body fields will be moved to complex attributes once the
|
||||
semantic convention tooling supports complex attributes
|
||||
(see [#1870](https://github.com/open-telemetry/semantic-conventions/issues/1870)).
|
||||
|
||||
| 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] |  |
|
||||
|
||||
**[1] `value`:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `value` should be treated as opt-in.
|
||||
|
||||
<!-- markdownlint-restore -->
|
||||
<!-- prettier-ignore-end -->
|
||||
<!-- END AUTOGENERATED TEXT -->
|
||||
|
|
|
|||
|
|
@ -18,6 +18,11 @@ groups:
|
|||
- ref: feature_flag.result.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.provider.name
|
||||
requirement_level: recommended
|
||||
- ref: feature_flag.context.id
|
||||
|
|
@ -52,18 +57,3 @@ groups:
|
|||
note: >
|
||||
Should not simply duplicate the value of `error.type`, but should provide more context.
|
||||
For example, if `error.type` is `invalid_context` the `error.message` may enumerate which context keys are missing or invalid.
|
||||
body:
|
||||
id: feature_flag.evaluation
|
||||
type: map
|
||||
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"]
|
||||
|
|
|
|||
|
|
@ -88,3 +88,14 @@ groups:
|
|||
examples: ["static", "targeting_match", "error", "default"]
|
||||
brief: >
|
||||
The reason code which shows how a feature flag value was determined.
|
||||
- id: feature_flag.result.value
|
||||
type: any
|
||||
stability: development
|
||||
examples: ["#ff0000", true, 3]
|
||||
brief: The evaluated value of the feature flag.
|
||||
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 is left to the instrumentation author to determine how best to achieve this.
|
||||
|
|
|
|||
Loading…
Reference in New Issue