Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Feature Flag evaluation event #1440

Draft
wants to merge 8 commits into
base: main
Choose a base branch
from
Draft

Feature Flag evaluation event #1440

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
64cc6e1
Feature Flag: feature_flag.evaluation event
dyladan Sep 30, 2024
9d70d52
Remove ff events.yaml for now
dyladan Sep 30, 2024
17661ad
Deprecate
dyladan Sep 30, 2024
5a1315f
Fix lint errors
dyladan Sep 30, 2024
778a506
Add changelog entry
dyladan Sep 30, 2024
955784e
Merge branch 'main' into ff-evaluation-event
dyladan Sep 30, 2024
5353b33
Merge remote-tracking branch 'origin/main' into ff-evaluation-event
dyladan Oct 14, 2024
1b2d939
Update ff version to be clear a hash is not a specific recommendation
dyladan Oct 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .chloggen/1140.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
change_type: enhancement
component: feature_flag
note: Define `feature_flag.evaluation` event.
issues: [1140]
25 changes: 20 additions & 5 deletions docs/attributes-registry/feature-flag.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,22 @@

# 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.

| 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) |
dyladan marked this conversation as resolved.
Show resolved Hide resolved

**[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
Expand All @@ -24,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)<br>Replaced by `feature_flag.provider.id`. |
14 changes: 9 additions & 5 deletions docs/feature-flags/feature-flags-logs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- semconv log-feature_flag -->
<!-- semconv feature_flag.evaluation -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

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
Expand Down
76 changes: 0 additions & 76 deletions docs/feature-flags/feature-flags-spans.md
View file
Open in desktop

This file was deleted.

12 changes: 12 additions & 0 deletions model/feature-flag/deprecated/registry-deprecated.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"]
14 changes: 0 additions & 14 deletions model/feature-flag/events.yaml
View file
Open in desktop

This file was deleted.

21 changes: 16 additions & 5 deletions model/feature-flag/logs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
26 changes: 25 additions & 1 deletion model/feature-flag/registry.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ groups:
stability: experimental
brief: The unique identifier of the feature flag.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed, I suggested to rename to "The lookup key of the feature flag."

examples: ["logo-color"]
- id: feature_flag.provider_name
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest leaving this open. Using an "id" means it is "blocked" only to use IDs, and we can potentially use it for names or other semantically valid values.
I would allow you to use the following examples:
["provider-1", "guid_here", "provider-v1"]

- id: feature_flag.provider.id
type: string
stability: experimental
brief: The name of the service provider that performs the flag evaluation.
Expand All @@ -31,3 +31,27 @@ 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.
Comment on lines +52 to +57
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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.
- id: feature_flag.flag_set.id
type: string
stability: experimental
examples: ["proj-1", "ab98sgs", "service1/dev"]
brief: >
The identifier of the flag set, which the feature flag belongs to in a flag management system.

A flag set is defined here as `A collection of related flags. This grouping helps organize feature flags based on their intended use, facilitating easier management and deployment.

Loading