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.