Sentry Feature Flags（FlagPole）实践指南：从注册、检查到灰度发布的完整流程

Sentry Feature Flags（FlagPole）实践指南：从注册、检查到灰度发布的完整流程

【免费下载链接】sentryDeveloper-first error tracking and performance monitoring项目地址: https://gitcode.com/GitHub_Trending/sen/sentry

本文为 Sentry 仓库中 Feature Flag 工作流的系统化指南，基于 .agents/skills/feature-flags/SKILL.md 展开。读完你将掌握：如何在 temporary.py 中注册一个新特性开关、如何在 Python 与前端代码中检查开关、如何在测试中临时打开开关，以及 FlagPole 灰度配置（segments/conditions/rollout）的底层评估模型与下线路径。

核心结论：新功能必须挂在特性开关后面

Sentry 的工程规范要求：新开发的功能应当被一个 feature flag 保护（gated behind a feature flag）。这样功能可以在未发布前对部分组织/用户灰度放量，出现问题可以秒级回滚，上线完成后再按固定流程清理。

Sentry 的开关体系由两部分组成：

• 注册与检查层：位于 src/sentry/features/，核心是FeatureManager，负责开关的注册、默认值管理与求值顺序；
• 评估引擎层：位于 src/flagpole/（FlagPole），一个“由 options 驱动的特性开关引擎”，通过 YAML 配置描述 segments（分段）与 conditions（条件），决定某个开关对某个组织/用户是否生效。

两者的衔接点正是FeatureHandlerStrategy.FLAGPOLE这个策略枚举，定义在 base.py：

class FeatureHandlerStrategy(Enum): INTERNAL = 1 """ Handle the feature using a logic within a FeatureHandler subclass """ FLAGPOLE = 2 """ Handle the feature using Flagpole and option backed rules based features. Features will automatically have options registered for them. """

INTERNAL表示开关由代码内的FeatureHandler子类决定；FLAGPOLE表示开关由远程可修改的 option 配置驱动——新增开关几乎都应选择后者。

第一步：在 temporary.py 中注册开关

基本注册方式

在 src/sentry/features/temporary.py 中调用manager.add：

manager.add("organizations:my-feature", OrganizationFeature, FeatureHandlerStrategy.FLAGPOLE, api_expose=True)

各参数的含义（对照 manager.py 的FeatureManager.add签名）：

作用域类的对应关系在 base.py 中定义：OrganizationFeature携带organization实例；ProjectFeature携带project实例，但其get_subject()返回的是project.organization（项目级开关最终也按组织维度求值）；SystemFeature没有实体上下文，只依赖应用配置。

FLAGPOLE 注册的隐藏动作：自动注册 option

这是理解整个体系的关键。阅读 manager.py 可以看到：

entity_feature_strategy = self._shim_feature_strategy(entity_feature_strategy) if entity_feature_strategy == FeatureHandlerStrategy.FLAGPOLE: if name.startswith("users:"): raise NotImplementedError("User flags not allowed with entity_feature=True") self.entity_features.add(name) # Register all flagpole features with options automator, # so long as they haven't already been registered. if ( entity_feature_strategy == FeatureHandlerStrategy.FLAGPOLE and name not in self.flagpole_features ): self.flagpole_features.add(name) # Set a default of {} to ensure the feature evaluates to None when checked feature_option_name = f"{FLAGPOLE_OPTION_PREFIX}.{name}" options.register( feature_option_name, type=Dict, default={}, flags=options.FLAG_AUTOMATOR_MODIFIABLE )

也就是说，当你用FLAGPOLE策略注册organizations:my-feature时，系统会自动注册一个名为feature.organizations:my-feature的 option（FLAGPOLE_OPTION_PREFIX = "feature"），类型为Dict，默认值{}，且带FLAG_AUTOMATOR_MODIFIABLE标记——即允许由 options automator 管道修改。这意味着：

1. 每个 FlagPole 开关本质上就是一个 option，灰度配置写入这个 option 的字典值中；
2. 空字典{}会让评估“弃权”（evaluate to None），最终回落到default参数或settings.SENTRY_FEATURES，保证未配置时行为可控；
3. users:前缀的开关不允许走 FLAGPOLE 策略（直接抛NotImplementedError）。

temporary 与 permanent 的区别

• temporary.py：灰度中的临时开关，全量后会被删除；
• permanent.py：永久开关，通常是订阅套餐（plan/tier）权益的一部分，例如organizations:sso-saml2、projects:rate-limits等。从源码注释看，控制套餐权益的开关应当从temporary.py移到permanent.py而不是删除，且理想情况下应在sentry/conf/server.py中同步配置，使自托管与单租户版本与 sentry.io 对齐。

两个注册函数由 features/init.py 统一挂载到全局default_manager：

default_manager = FeatureManager() # NOQA register_permanent_features(default_manager) register_temporary_features(default_manager) # expose public api add = default_manager.add has = default_manager.has batch_has = default_manager.batch_has ...

__init__.py头部的模块注释也是官方使用文档：先确定作用域（organization/project），再决定是否api_expose（不在前端使用的开关不要 expose，因为特征检查会增加组织/项目详情响应的延迟和体积），最后设置默认值。

第二步：Python 端检查开关

标准检查写法：

if features.has("organizations:my-feature", organization, actor=user):

actor参数表示“以哪个用户的身份求值”，FlagPole 的用户级条件（如按user_email、user_domain灰度）依赖它。

从 FeatureManager.has 的 docstring 与实现看，检查顺序是三级回落：

1. 已注册的FeatureHandler：按注册顺序执行，任何一个 handler 返回True/False即终止；返回None则交给下一个 handler；
2. entity handler：即 FlagPole 对应的实体处理器（在 getsentry 中为FlagpoleFeatureHandler），这是 FLAGPOLE 策略开关真正求值的地方；
3. 默认值：settings.SENTRY_FEATURES.get(feature.name, False)，即注册时的default；再之后一律按False处理。

此外每次求值都会打点（features.has计时、feature.has.result计数）并通过record_feature_flag记录开关结果，且整体被 try/except 包裹——求值异常时返回False并按features.error.capture_rate采样上报，即开关故障永远朝“关”方向退化。

批量场景有三个补充 API（同样定义在 manager.py）：

• has_for_batch(name, organization, [project1, project2], actor=...)：一次检查同一开关在多个项目上的结果，适合“只依赖组织属性”的批量判断，避免逐个查询；
• batch_has(feature_names, actor, projects, organization)：一次检查多个开关，要求全部同属 Project 或 Organization 作用域，返回按organization:{id}/project:{id}分组的结果；
• batch_has_for_organizations(feature_name, organizations)：同一开关在多个组织上的批量检查。

第三步：前端检查开关（需要 api_expose=True）

只有注册时指定了api_expose=True的开关才会进入组织序列化结果，前端才能这样检查：

organization.features.includes('my-feature');

从源码结构看，api_expose=True会把开关名加入FeatureManager.exposed_features集合（manager.py），而all(feature_type, api_expose_only=True)正是序列化器用来筛选“应暴露给前端的开关”的入口。注意前端拿到的是去掉organizations:前缀后的名字，这与 Python 端使用全名形成对照。

另外，删除开关时如果漏掉了前端检查点，由于该名字不再出现在features数组中，includes会静默返回false而非报错——这正是下线路程中要求“前端收敛必须先行部署”的原因。

第四步：测试中临时打开开关

Sentry 测试基类提供了上下文管理器（testutils/cases.py）：

def feature(self, names): """ >>> with self.feature({'feature:name': True}) >>> # ... """ return Feature(names)

实际使用（Skill 文档中的标准写法）：

with self.feature("organizations:my-feature"): ...

Feature上下文管理器会在with块内临时注入OrganizationFeature处理器，使开关在块内恒为True，退出后恢复——不需要真正写 FlagPole 配置就能覆盖“开启分支”的测试路径。反过来，不打开开关走默认值分支的测试同样应存在，两条分支都应断言。

FlagPole 的评估模型：segments、conditions 与 rollout

FlagPole 引擎在 src/flagpole/init.py 的模块 docstring 中给出了配置形态——每个开关是一份 YAML，包含enabled、owner、segments，每个 segment 可带rollout（百分比放量）和若干conditions：

features: organizations:fury-mode: enabled: True name: sentry organizations owner: team: hybrid-cloud segments: - name: sentry orgs rollout: 50 conditions: - property: organization_slug name: internal organizations operator: kind: in value: ["sentry-test", "sentry"] - name: free accounts conditions: - property: subscription_is_free name: free subscriptions operator: kind: equals value: True

评估语义（对照 Feature.match）：

• enabled: False直接为False；
• 遍历 segments，任一 segment 的所有 conditions 全部命中即视为匹配，再按该 segment 的rollout百分比（segment.in_rollout(context)）决定最终结果；
• 没有任何 segment 命中则为False；空 segments 列表恒为False。

配置结构由 flagpole-schema.json 校验（Feature.validate()使用 jsonschema 做严格验证），条件操作符支持in、equals等 kind（见 conditions.py）。

评估上下文：Sentry 给 FlagPole 喂什么数据

conditions 引用的 property 来自应用侧构建的评估上下文。flagpole_context.py 定义了 Sentry 的上下文转换器，可用的 property 包括：

• 组织维度：organization_slug、organization_name、organization_id、organization_is-early-adopter（且兼容Organization、OrganizationMapping、RpcOrganization等跨 silo 的多种表示）；
• 项目维度：project_slug、project_name、project_id、project_platform；
• 用户维度：user_id、user_is-superuser、user_is-staff，以及仅在邮箱已验证时暴露的user_email、user_domain。

由 get_sentry_flagpole_context_builder 将这些 transformer 组装成ContextBuilder，也就是说 YAML 里写property: organization_slug时，能匹配到的就是组织 slug。此外 flagpole/init.py 还定义了experiment_mode（simple模式：flag 开 = active 组，flag 关 = control 组），配合FeatureManager.get_experiment_assignments可把开关求值直接当实验分组使用。

灰度发布：配置存放在哪里

Skill 文档明确指出：FlagPole 的 YAML 灰度配置不在本仓库，而在独立的sentry-options-automator仓库。这是因为每个 FLAGPOLE 开关自动注册出的feature.<name>option 带FLAG_AUTOMATOR_MODIFIABLE标记，由 automator 的管道统一写入与校验。因此在 sentry 仓库内你只能看到开关的注册与默认值，看不到放量百分比与条件；调整灰度要去 automator 侧的options/default/flagpole.yaml（以及可能的 region 文件）操作。

下线：固定的三 PR 顺序

开关全量后不能随手删注册行。remove-option-or-flag/SKILL.md 规定了三 PR 固定顺序，每一步必须部署完成（不只是合并）后才能进入下一步：

顺序错误的代价在文档中写得很具体：FLAGPOLE 开关删除 automator 配置后会回落到自动注册的{}→ FlagPole 弃权 →settings.SENTRY_FEATURES中的default（通常为False），即开关会对所有人关闭，而不是保持在 100%；反之若先删注册、配置还在，automator 会因unregistered option报错，漂移检查变红。

速查小结

【免费下载链接】sentryDeveloper-first error tracking and performance monitoring项目地址: https://gitcode.com/GitHub_Trending/sen/sentry