Semantic Conventions for Feature Flags in Spans
Status: Experimental
This document defines semantic conventions for recording dynamic feature flag evaluations within a transaction as span events. To record an evaluation outside of a transaction context, consider recording it as a log record.
Motivation
Features flags are commonly used in modern applications to decouple feature releases from deployments. Many feature flagging tools support the ability to update flag configurations in near real-time from a remote feature flag management service. They also commonly allow rulesets to be defined that return values based on contextual information. For example, a feature could be enabled only for a specific subset of users based on context (e.g. users email domain, membership tier, country).
Since feature flags are dynamic and affect runtime behavior, it’s important to collect relevant feature flag telemetry signals. This can be used to determine the impact a feature has on a request, enabling enhanced observability use cases, such as A/B testing or progressive feature releases.
Overview
The following semantic convention defines how feature flags can be represented as an Event in OpenTelemetry.
The terminology was defined in the OpenFeature specification, which represents an industry consensus.
It’s intended to be vendor neutral and provide flexibility for current and future use cases.
Convention
A flag evaluation SHOULD be recorded as an Event on the span during which it occurred.
The event name MUST be feature_flag.
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
feature_flag.key | string | The unique identifier of the feature flag. | logo-color | Required |
feature_flag.provider_name | string | The name of the service provider that performs the flag evaluation. | Flag Manager | Recommended |
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 | Recommended |
[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
provide additional context for understanding the meaning behind a value.
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.