功能标志事件的语义约定

状态: 开发中

动机

功能标志通常用于现代应用程序中，以将功能发布与部署解耦。许多功能标志工具支持从远程功能标志管理服务实时更新标志配置。它们通常还允许定义基于上下文信息返回值的规则集。例如，一个功能可以仅对特定用户子集启用，基于上下文（例如，用户的电子邮件域、会员等级、国家/地区）。

由于功能标志是动态的并且会影响运行时行为，因此收集相关功能标志遥测信号非常重要。这可以用于确定功能对请求的影响，从而实现增强的可观察性用例，例如 A/B 测试或渐进式功能发布。

记录评估

功能标志评估应记录为传递给 Event 的属性，该 Event 通过 Logger emit 操作。

注意：事件尚处于开发中，尚未在某些语言中提供。请查看 合规性矩阵 以查看相应语言中的实现状态。

评估事件

下表显示了应添加到 Event 的属性及其类型。

状态：

事件名称必须是 feature_flag.evaluation。

将功能标志评估定义为事件。

当功能标志值被评估时（这可能在应用程序生命周期中发生很多次），应发出 feature_flag.evaluation 事件。例如，一个对不同动画进行 A/B 测试的网站，每次按钮被点击时都可能评估一个标志。即使结果相同，也会在每次评估时发出 feature_flag.evaluation 事件。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
feature_flag.key		必需	字符串	功能标志的查找键。	logo-color
error.type		有条件地必需 [1]	字符串	描述操作结束时发生的错误类型。[2]	provider_not_ready；targeting_key_missing；provider_fatal；general
feature_flag.result.value		有条件地必需 [3]	any	功能标志的评估值。[4]	#ff0000；true；3
feature_flag.result.variant		有条件地必需 [5]	字符串	评估标志值的语义标识符。[6]	red；true；on
error.message		推荐 [7]	字符串	提供有关错误的更多详细信息的易读消息。[8]	Unexpected input type: string；The user has exceeded their storage quota
feature_flag.context.id		推荐	字符串	标志评估上下文的唯一标识符。例如，目标键。	5157782b-2203-4c80-a857-dbbd5e7761db
feature_flag.provider.name		推荐	字符串	标识功能标志提供商。	Flag Manager
feature_flag.result.reason		推荐	字符串	原因代码，显示功能标志值的确定方式。	static；targeting_match；error；default
feature_flag.set.id		推荐	字符串	功能标志所属的 flag set 的标识符。	proj-1；ab98sgs；service1/dev
feature_flag.version		推荐	字符串	评估期间使用的规则集的版本。这可以是唯一标识规则集的任何稳定值。	1；01ABCDEF

[1] error.type：仅当功能标志评估期间发生错误时。

[2] error.type：如果其中一个值适用，则必须使用；否则，可以使用自定义值。

值	描述	Stability
flag_not_found	找不到标志。
invalid_context	评估上下文不满足提供商的要求。
parse_error	解析数据（例如，标志配置）时遇到错误。
provider_fatal	提供商进入了不可恢复的错误状态。
provider_not_ready	在提供商初始化之前解析了该值。
targeting_key_missing	提供商需要一个目标键，但评估上下文中未提供。
type_mismatch	标志值类型与预期类型不匹配。
general	错误原因未在上文列出。

[3] feature_flag.result.value：仅当功能标志提供商不提供变体或等效概念时。否则，feature_flag.result.value 应视为选择加入。

[4] feature_flag.result.value：对于某些功能标志提供商，功能标志结果可能非常大或包含私密或敏感详细信息。因此，如果可用，feature_flag.result.variant 通常是首选属性。

如果可能，最好能编辑或以其他方式限制 feature_flag.result.value 的大小和范围。由于评估的标志值是非结构化的，可以是任何类型，因此由仪器作者决定如何最好地实现这一点。

[5] feature_flag.result.variant：如果功能标志提供商提供变体或等效概念。

[6] feature_flag.result.variant：语义标识符，通常称为变体，提供了一种引用值而不包含值本身的方法。这可以为理解值背后的含义提供额外的上下文。例如，变体 red 可能用于值 #c05543。

[7] error.message：仅当功能标志评估期间发生错误，并且 error.type 未充分描述错误时。

[8] error.message：不应简单复制 error.type 的值，而应提供更多上下文。例如，如果 error.type 是 invalid_context，则 error.message 可能会列出哪些上下文键缺失或无效。

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
_OTHER	当检测不到自定义值时使用的回退错误值。

feature_flag.result.reason 具有以下已知值列表。如果其中一个适用，则必须使用相应的 reason 值；否则，可以使用自定义值。

值	描述	Stability
cached	已从缓存中检索到解析值。
default	解析值回退到预配置的值（未发生动态评估或动态评估未产生结果）。
disabled	解析值是由于管理系统中禁用了该标志的结果。
错误	解析值是由于错误的结果。
split	解析值是伪随机分配的结果。
stale	解析值是非权威的或可能已过时。
static	解析值为静态（无动态评估）。
targeting_match	解析值是动态评估的结果，例如规则或特定用户定位。
unknown	无法确定解析值的原因。