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.


The table below indicates which attributes should be added to the LogRecord and their types.

The event name MUST be feature_flag.

AttributeTypeDescriptionExamplesRequirement LevelStability
feature_flag.keystringThe unique identifier of the feature flag.logo-colorRecommendedExperimental
feature_flag.provider_namestringThe name of the service provider that performs the flag evaluation.Flag ManagerRecommendedExperimental
feature_flag.variantstringSHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1]red; true; onRecommendedExperimental

[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.