From 51efc3385b1ce3bca3900b60d5859364a2f9bdf5 Mon Sep 17 00:00:00 2001 From: Simon Schrottner Date: Thu, 5 Jun 2025 08:37:32 +0200 Subject: [PATCH 1/3] feat: add standardized Propagation Evaluation to Flag Metadata. Within a lot of system flag changes are propagated asynchronously to the consumers (not during evaluations). This propagations can be enhanced via spans and traces on their own to see how flag changes are distributed throughout the system. But in the end, as an enduser i am curious, which propagation event actually is linked to my evaluation. It is possible to somehow determine this via version, but spans and traces offer a deeper insight. If we standardize this behaviour, we can create out of the box OpenTelemetry Configuration Changed Listeners, to make this feature usable with all our providers. --- specification/appendix-d-observability.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 9e33e28b..c3d73590 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -51,6 +51,15 @@ The following describes how keys in [flag metadata](types.md#flag-metadata) are | ---------------------------- | ----------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------ | | `feature_flag.provider.name` | `name` | `Recommended` | `string` | The name of the provider as defined in the `provider metadata`, available in the `hook context`. | +### Propagation Metadata + +Feature Flags are propagated through different systems with different methods. Often this updates have an asynchronous nature to the evaluation and do not correlate directly (eg. cached values or in-process evaluations). For distributed systems it is important to reflect how changes are populate to all systems, and how those correlate with evaluations. In a simple manner the version could be used to achieve this, but offers additional and more complex solution to correlate the data. Instead we are defining two additional metadata properties `propagationTraceId` and `propagationSpanId` which can be used to link evaluation spans to propagation spans. + +| Provider Metadata Field | Requirement level | Type | Notes | +| ----------------------- | ----------------- | -------- | -------------------------------------- | +| `propagationSpanId` | `Optional` | `string` | The span id of the propagation event. | +| `propagationTraceId` | `Optional` | `string` | The trace id of the propagation event. | + ## History Feature flags in the OpenTelemetry semantic conventions are currently in development and are marked as experimental. From f100365518f31cf00134d125f0337dc5efa283f9 Mon Sep 17 00:00:00 2001 From: Simon Schrottner Date: Tue, 30 Sep 2025 08:49:22 +0200 Subject: [PATCH 2/3] Update specification/appendix-d-observability.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Simon Schrottner --- specification/appendix-d-observability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index 7336f674..eda286b4 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -55,7 +55,7 @@ The following describes how keys in [flag metadata](types.md#flag-metadata) are Feature Flags are propagated through different systems with different methods. Often this updates have an asynchronous nature to the evaluation and do not correlate directly (eg. cached values or in-process evaluations). For distributed systems it is important to reflect how changes are populate to all systems, and how those correlate with evaluations. In a simple manner the version could be used to achieve this, but offers additional and more complex solution to correlate the data. Instead we are defining two additional metadata properties `propagationTraceId` and `propagationSpanId` which can be used to link evaluation spans to propagation spans. -| Provider Metadata Field | Requirement level | Type | Notes | +| Flag Metadata Key | Requirement level | Type | Notes | | ----------------------- | ----------------- | -------- | -------------------------------------- | | `propagationSpanId` | `Optional` | `string` | The span id of the propagation event. | | `propagationTraceId` | `Optional` | `string` | The trace id of the propagation event. | From 0b65bd8e315884940118615a91401a86e5b05275 Mon Sep 17 00:00:00 2001 From: Simon Schrottner Date: Tue, 30 Sep 2025 08:49:29 +0200 Subject: [PATCH 3/3] Update specification/appendix-d-observability.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Simon Schrottner --- specification/appendix-d-observability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendix-d-observability.md b/specification/appendix-d-observability.md index eda286b4..f9aa0484 100644 --- a/specification/appendix-d-observability.md +++ b/specification/appendix-d-observability.md @@ -53,7 +53,7 @@ The following describes how keys in [flag metadata](types.md#flag-metadata) are ### Propagation Metadata -Feature Flags are propagated through different systems with different methods. Often this updates have an asynchronous nature to the evaluation and do not correlate directly (eg. cached values or in-process evaluations). For distributed systems it is important to reflect how changes are populate to all systems, and how those correlate with evaluations. In a simple manner the version could be used to achieve this, but offers additional and more complex solution to correlate the data. Instead we are defining two additional metadata properties `propagationTraceId` and `propagationSpanId` which can be used to link evaluation spans to propagation spans. +Feature Flags are propagated through different systems with different methods. Often these updates have an asynchronous nature to the evaluation and do not correlate directly (eg. cached values or in-process evaluations). For distributed systems it is important to reflect how changes are populated to all systems, and how those correlate with evaluations. In a simple manner the version could be used to achieve this, but it offers a more complex solution to correlate the data. Instead we are defining two additional metadata properties `propagationTraceId` and `propagationSpanId` which can be used to link evaluation spans to propagation spans. | Flag Metadata Key | Requirement level | Type | Notes | | ----------------------- | ----------------- | -------- | -------------------------------------- |