Semantic Conventions for Feature Flags in Logs
Status: Experimental
This document defines semantic conventions for recording feature flag evaluations as a log record emitted through the Logger API. This is useful when a flag is evaluated outside of a transaction context such as when the application loads or on a timer. To record a flag evaluation as a part of a transaction context, consider recording it as a span event.
For more information about why it is useful to capture feature flag evaluations, refer to the motivation section of the trace semantic convention for feature flag evaluations.
Recording an Evaluation
Feature flag evaluations SHOULD be recorded as attributes on the LogRecord passed to the Logger emit operations. Evaluations MAY be recorded on “logs” or “events” depending on the context.
Attributes
The table below indicates which attributes should be added to the LogRecord and their types.
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.