Skip to content

feat: add standardized Propagation Evaluation to Flag Metadata. #313

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat: add standardized Propagation Evaluation to Flag Metadata. #313

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
9 changes: 9 additions & 0 deletions specification/appendix-d-observability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
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 to it (eg. cached values or in-process evaluations). For distributed systems it is important to reflect how changes in flag configurations are propagated 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.

Copy link
Member

Choose a reason for hiding this comment

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

Instead we

I would not use first person here.

Copy link
Member

Choose a reason for hiding this comment

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

propagationTraceId and propagationSpanId

I have some things that are not fully clear to me from reading this:

How are these defined?
Do we typically fill these with the OTEL values? Which span do we use then? Trace would probably be the root one?
How are we setting them?

Copy link
Member Author

Choose a reason for hiding this comment

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

The propagationTraceId and propagationSpanId are flexible. eg. in flagd we would create a trace and span for each GRPC event and add this information to the payload. eg. GRPC streams don't offer a way to propagate headers for events only, they have to be part of the payload. Other connection methods might autopropagate them if possible. But with the persistence in the metadata, we can link the propagating span to the evaluating span (which might be two totally different occasions/traces).

I am not the best one, when writing specs, this is my first attempt, and I am happy to explain my thoughts, and maybe this will help to solve the confusion

Copy link
Member

Choose a reason for hiding this comment

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

But with the persistence in the metadata, we can link the propagating span to the evaluating span (which might be two totally different occasions/traces).

I get that concept.

What I am not sure about is, how do we define all these things exactly.
E.g. for the propagating span I can imagine multiple definitions, one of them being `the span of the incoming http request".
This span id e.g. will be different between all services, the traceparent id in otel might be the same between all of the services. This part is not shown in your example.

Maybe it is good enough to add 1 or 2 good examples for a good value for the ids.

Copy link
Member

Choose a reason for hiding this comment

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

In a simple manner the version could be used to achieve this, but offers additional and more complex solution to correlate the data.

Do you mean the version that we defined on the OTEL semconv?
What do you mean by "offers additional and more complex solution"?

Copy link
Member Author

Choose a reason for hiding this comment

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

In appendix D, we specify that flag metadata can contain a version https://openfeature.dev/specification/appendix-d#flag-metadata - theoretically,y we could use the version field too, to link the propagating span/trace, to the evaluation span/trace.

Copy link
Member

Choose a reason for hiding this comment

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

In appendix D, we specify that flag metadata can contain a version

Yeah, I mean, that I would love this to be a bit more clear that this version is used.

theoretically,y we could use the version field too, to link the propagating span/trace, to the evaluation span/trace.

Okay, but what what do you mean with: but offers additional and more complex solution to correlate the data.?

Copy link
Member Author

@aepfli aepfli Jun 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

we could use this version to correlate, but this proposal adds another attribute, which contains the traceid and spanid of the propagating cause.

eg. in flagd in-process, we have two non-connected steps for evaluations.

  1. Flag configurations are distributed asynchronously. When Flagd detects a change in the flag source, it sends out a new configuration, which will have a version attribute in the metadata.
  2. When I do evaluations, I can create a new span, and if I want to correlate this with the span of the propagation, I need to check for the version attribute, and I don't have a direct link. Otel offers to link traces, to represent a correlation. With the information of the trace and span, we can create this link. And create a holistic image from propagation span to evaluation span, and how it is linked.


| 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.
Expand Down
Loading