Help us learn about your current experience with the documentation. Take the survey.

使用 ChatOps 启用和禁用功能标志

本文档说明如何参与 GitLab 产品的开发工作。 如果您想在自己的应用程序中使用功能标志来显示和隐藏功能， 请查看此功能标志信息。

要在任何 GitLab 提供的环境（如 staging 和 production）中启用/禁用功能标志背后的功能， 您需要拥有 ChatOps 机器人的访问权限。ChatOps 机器人目前运行在 ops 实例上， 该实例与 GitLab.com 或 dev.gitlab.org 不同。

按照 ChatOps 文档请求访问。

添加到项目后，测试您的访问权限是否已生效，请运行：

/chatops run feature --help

逐步推出变更

当变更部署到环境后，就可以开始向用户推出该功能了。 推出变更的具体流程未明确规定，因为这可能因变更而异。 但是，通常我们建议逐步推出变更，而不是立即为所有人启用。 我们还建议您不要在代码部署之前启用功能。 这可以将功能推出与部署分开，使您能够更容易地分别衡量两者的影响。

GitLab 功能库（使用 Flipper，并在 功能标志流程指南中介绍） 支持向用户按百分比推出变更。 这可以通过 GitLab ChatOps 进行控制。

有关功能标志命令的最新列表，请参见 源代码。 该文件中的所有示例都必须以 /chatops run 开头。

如果您收到错误消息"哎呀！此操作不被允许。此事件将被报告。"， 这意味着您的 Slack 账户不允许更改功能标志，或者您没有访问权限。

为预生产测试启用功能

作为功能推出的第一步，您应该在 staging.gitlab.com 和 dev.gitlab.org 上启用该功能。

这两个环境有不同的范围。 dev.gitlab.org 是一个生产 CE 环境，有内部 GitLab Inc. 的流量， 用于一些开发和其他相关工作。 staging.gitlab.com 拥有 GitLab.com 数据库和存储库的较小子集， 没有常规流量。Staging 是一个 EE 实例，可以为您提供（非常）粗略的估计， 说明您的功能在 GitLab.com 上的外观和行为。 这两个实例都连接到 Sentry，因此在启用功能标志后测试您的功能时， 请务必检查那里的项目是否有任何异常。

对于这些预生产环境，强烈建议在 #staging、#production 或 #chat-ops-test 中运行命令， 以提高可见性。

为给定百分比的行为者启用功能标志

要为任何给定行为者 25% 的时间启用功能，请在 Slack 中运行以下命令：

/chatops run feature set new_navigation_bar 25 --actors --dev
/chatops run feature set new_navigation_bar 25 --actors --staging

有关您希望随机推出的行为者的选择，请参见行为者百分比。

为 GitLab.com 启用功能

当功能已成功 在预生产环境中启用 并验证为安全且正常工作后，您可以将变更推出到 GitLab.com（生产环境）。

如果功能已弃用，请不要启用该标志。

传达变更

GitLab.com 上的一些功能标志变更需要与公司部分人员进行沟通。 负责的开发人员需要确定这是否必要以及适当的沟通级别。 这取决于功能及其可能产生的影响。

指导原则：

  • 事先通知 #support_gitlab-com。这样，如果功能对用户体验有任何副作用， 他们可以减轻影响并禁用功能标志以减少一些影响。
  • 如果功能符合创建变更管理问题的要求， 请按照严重性指导原则创建变更管理问题。
  • 对于简单、低风险、易于恢复的功能，继续并在#production中启用该功能。
  • 对于为特定组或项目切换功能标志的支持请求，请遵循支持工作流程中概述的流程。

推出期间选择百分比的指导原则

推出功能标志时选择哪个百分比取决于不同因素，例如：

  • 功能标志是否经常检查，以便您可以收集足够的信息来决定继续推出是否安全？
  • 如果功能出现问题，会有多少请求或客户受到影响？
  • 如果出现问题，是否有其他 GitLab 公开功能会受到推出的影响？
  • 推出功能标志是否可能导致性能下降？

让我们举一些不同类型功能标志的例子，以及您如何考虑在这些情况下的推出：

A. 每天运行几次的操作的功能标志

例如，您正在发布一个新功能，该功能在 cron 作业中每天运行几次，并且该功能由新引入的功能标志控制。 例如，重写 cron 作业的数据库查询。 在这种情况下，以低于 25% 的百分比发布功能标志可能会给您关于是否继续推出的反馈较慢。 此外，如果 cron 作业失败，它会重试。 因此，出现问题的后果不会那么大。在这种情况下，以 25% 或 50% 的百分比发布是可以接受的选择。

但您必须确保将功能标志检查的结果记录到您的工作日志中。有关日志记录最佳实践的更多说明，请参见 日志上下文元数据（通过 Rails 或 Grape 请求）。

B. 每天运行数百或数千次的操作的功能标志

您新引入的功能或变更可能比 Sidekiq 作业中运行的任何功能面向客户更多。 但它可能不经常运行。在这种情况下，选择足够高的百分比以收集一些结果， 以便知道是否继续。在这种情况下，您可以考虑从 5% 或 10% 开始， 同时监控日志中的任何错误，或返回给用户的 500 状态码。

但随着您继续推出并增加百分比，您需要考虑查看功能的性能影响。 您可以考虑监控 Grafana 上的 延迟：Apdex 和错误比率仪表板。

C. 在应用程序核心运行的操作的功能标志

有时，新的变更可能会影响 GitLab 应用的各个方面。例如，更改 核心模型（如 User、Project 或 Namespace）上的数据库查询。 在这种情况下，建议以 1% 的请求发布功能，甚至更少（通过变更请求）， 以避免任何事故。请参见此变更请求示例， 该功能标志针对大约 0.1% 的请求发布，因为变更的影响很大。

为确保推出不会影响许多客户，请考虑遵循以下步骤：

  1. 估算 100% 功能标志推出可能影响的每分钟请求数量。 这可以通过跟踪数据库查询来实现。请参见这里的说明。
  2. 计算在推出不如预期的情况下合理受影响的请求数或用户数。
  3. 根据从 (1) 和 (2) 收集的数字，计算合理的起始百分比来推出功能标志。 这是一个示例。
  4. 确保在功能标志的推出问题上传达您的发现。
D. 发布功能标志的未知影响

如果您不确定使用哪个百分比，请选择安全推荐的选项，并选择这些百分比：

  1. 1%
  2. 10%
  3. 25%
  4. 50%
  5. 75%
  6. 100%

在每个步骤之间，您需要等待一段时间并监控 https://dashboards.gitlab.net 上的相应图表。 等待的确切时间可能不同。对于某些功能，几分钟就足够了， 而对于其他功能，您可能需要等待几小时甚至几天。 这完全取决于您，只要您清楚地传达给您的团队和生产团队， 如果您预期任何潜在问题。

流程

当启用功能标志推出时，如果存在活跃的 "severity::1" 或 ~"severity::2" 事故 或进行中的变更问题，系统将自动阻止 ChatOps 命令成功执行，例如：

/chatops run feature set gitaly_lfs_pointers_pipeline true

- 生产检查失败！
- 活跃事故

  2021-06-29 金丝雀部署 failing QA tests

在启用功能标志之前，请验证您没有违反任何生产变更锁定期， 并符合功能标志和变更管理流程。

以下 /chatops 命令必须在 Slack 的 #production 频道中执行。

行为者百分比推出

要为 25% 的行为者（如用户、项目、组或当前请求或作业）启用功能， 请在 Slack 中运行以下命令：

/chatops run feature set some_feature 25 --actors

这将根据以下公式将功能标志设置为 true：

feature_flag_state = Zlib.crc32("some_feature<Actor>:#{actor.id}") % (100 * 1_000) < 25 * 1_000
# 其中 <Actor>: 是 `User`、`Group`、`Project`，actor 是一个实例

在开发过程中，应根据功能的性质选择行为者。

对于面向用户的功能：

Feature.enabled?(:feature_cool_avatars, current_user)

对于组或命名空间级别的功能：

Feature.enabled?(:feature_cooler_groups, group)

对于项目级别的功能：

Feature.enabled?(:feature_ice_cold_projects, project)

对于当前请求：

Feature.enabled?(:feature_ice_cold_projects, Feature.current_request)

功能门也可以基于行为者，例如功能可以先仅对 gitlab 项目启用。 通过提供 --project 标志来传递项目：

/chatops run feature set --project=gitlab-org/gitlab some_feature true

您可以使用 --user 选项为特定用户启用功能标志：

/chatops run feature set --user=myusername some_feature true

如果您想先收集内部反馈， 可以为 GitLab 团队成员启用用户范围的功能标志， 使用 gitlab_team_members 功能组：

/chatops run feature set --feature-group=gitlab_team_members some_feature true

您可以使用 --group 标志为特定组启用功能标志：

/chatops run feature set --group=gitlab-org some_feature true

请注意 --group 不适用于用户命名空间。要为通用命名空间（包括组）启用功能标志，请使用 --namespace：

/chatops run feature set --namespace=gitlab-org some_feature true
/chatops run feature set --namespace=myusername some_feature true

基于行为者的门会在百分比之前应用。例如，考虑 group/project 为 gitlab-org/gitlab，给定的示例功能为 some_feature， 如果您运行这两个命令：

/chatops run feature set --project=gitlab-org/gitlab some_feature true
/chatops run feature set some_feature 25 --actors

那么 some_feature 将为 25% 的行为者和与 gitlab-org/gitlab 交互时始终启用。 如果功能标志开发利用组行为者，这是一个好主意。

Feature.enabled?(:some_feature, group)

可以一起传递多个行为者，以逗号分隔的形式：

/chatops run feature set --project=gitlab-org/gitlab,example-org/example-project some_feature true

/chatops run feature set --group=gitlab-org,example-org some_feature true

/chatops run feature set --namespace=gitlab-org,example-org some_feature true

最后，为确保功能在尽可能多的情况下被认为是稳定的， 您应该通过运行以下命令全局启用标志来完全推出功能：

/chatops run feature set some_feature true

这会将功能标志状态更改为始终启用，覆盖上述过程中的现有门（例如 --group=gitlab-org）。

请注意，如果存在基于行为者的功能门，将 YAML 定义中的 default_enabled 属性从 false 切换到 true 不会有任何效果。 必须先删除该功能门。

例如，功能标志通过 ChatOps 设置：

/chatops run feature set --project=gitlab-org/gitlab some_feature true

当 YAML 定义中的 default_enabled 属性切换为 true 时，必须删除功能门才能达到预期效果：

/chatops run feature delete some_feature
时间百分比推出（已弃用）

以前，要启用功能 25% 的时间，我们会在 Slack 中运行以下命令：

/chatops run feature set new_navigation_bar 25 --random

此命令为 GitLab.com 启用 new_navigation_bar 功能。但是，此命令不会为 25% 的总用户启用该功能。 相反，当使用 enabled? 检查功能时，它 25% 的时间返回 true。

时间百分比功能标志现已弃用，支持使用 Feature.current_request 行为者的 行为者百分比。 不使用行为者的问题是，随机选择在每次调用 Feature.enabled? 时评估， 而不是每个请求或作业执行一次，这可能导致状态翻转。例如：

feature_flag_state = rand < (25 / 100.0)

目前，我们继续允许使用时间百分比功能标志。 在推出期间，您可以在 ChatOps 中使用 --ignore-random-deprecation-check 开关强制使用它。

禁用功能标志

要禁用已全局启用的功能标志，可以运行：

/chatops run feature set some_feature false

要禁用已为特定项目启用的功能标志，可以运行：

/chatops run feature set --project=gitlab-org/gitlab some_feature false

您不能在不应用功能标志的特定实现方法的情况下， 为特定项目/组/用户选择性地禁用功能标志。

如果功能标志通过 ChatOps 禁用，这将优先于 YAML 中的 default_enabled 值。 换句话说，您可以为本地安装启用功能，但不能为 GitLab.com 启用。

按行为者选择性地禁用

默认情况下，您不能按行为者选择性地禁用功能标志。

# 这不会按您预期的方式工作。
/chatops run feature set some_feature true
/chatops run feature set --project=gitlab-org/gitlab some_feature false

但是，如果您添加两个功能标志，您可以编写条件语句，以便实现等效的选择性禁用。

Feature.enabled?(:a_feature, project) && Feature.disabled?(:a_feature_override, project)
# 这将全局启用功能标志，但 gitlab-org/gitlab 除外
/chatops run feature set a_feature true
/chatops run feature set --project=gitlab-org/gitlab a_feature_override true

基于百分比的行为者选择

在使用多个功能标志的行为者百分比推出时，每个功能标志的行为者都是单独选择的。

例如，以下功能标志为一定百分比的行为者启用：

/chatops run feature set feature-set-1 25 --actors
/chatops run feature set feature-set-2 25 --actors

如果项目 A 启用了 :feature-set-1，不能保证项目 A 也启用了 :feature-set-2。

更多详情，请参见这是 Flipper 中百分比的工作原理。

启用功能标志后验证指标

启用功能标志后，您需要在每个步骤之间监控相关图表：

  1. 转到 dashboards.gitlab.net。
  2. 打开 feature-flag。
  3. 监视可能受您的变更影响的服务（如 sidekiq service、api service 或 web service）的 Latency: Apdex。 然后通过选择 Service Overview Dashboards 并选择可能与您的变更相关的仪表板来查看更深入的仪表板。

在此图中，您可以看到 Apdex 分数在 09:46 启用功能标志后开始下降。 然后在 10:31 停用了功能标志，服务恢复到原始值：

显示 Apdex 分数下降和恢复的线图

某些功能需要多天进行广泛监控，特别是那些高风险且对业务运营至关重要的功能。 相比之下，其他功能可能只需要 24 小时的监控期，然后继续推出。

建议在启动推出之前确定必要的监控范围。

功能标志变更日志记录

ChatOps 级别

任何通过 ChatOps 影响 GitLab.com（生产）的功能标志变更 都会自动记录在一个问题中。

问题创建在 gl-infra/feature-flag-log 项目中，它至少会记录启用功能标志的人员的 Slack 处理程序、时间和正在更改的标志名称。

然后，问题也会发布到 GitLab 内部的 Grafana 仪表板作为注释标记， 以使变更更加明显。

问题格式的更改可以在 ChatOps 项目中提交。

实例级别

任何影响任何 GitLab 实例的功能标志变更都会自动记录在 features_json.log 中。 您可以在 Kibana 中搜索变更历史。 您还可以访问 GitLab.com 的功能标志变更历史在 Kibana 中。

清理

功能标志一旦不再需要就应被移除。代码库中的每个额外功能标志都会增加应用程序的复杂性， 并降低我们对测试套件覆盖所有可能组合的信心。 此外，在某些环境中被覆盖的功能标志可能导致未定义和未经测试的系统行为。

development 类型的功能标志应有短生命周期，因为它们的目的是推出持久性变更。 超过 2 个里程碑的 development 功能标志会报告给工程经理。 报告工具每月运行一次。 例如，请参见2021 年 12 月的报告。

如果 development 功能标志在代码库中仍然存在 6 个月，我们应该采取以下行动之一：

  • 默认启用功能标志并移除它。
  • 将其转换为实例、组或项目设置。
  • 如果它仍然被禁用且不再需要，则回滚更改。

要移除功能标志，打开一个合并请求进行更改。在 MR 中：

  1. 添加 ~“feature flag” 标签，以便发布经理知道移除。
  2. 如果合并请求必须回溯到当前版本，请遵循 补丁发布运行手册流程。 更多详情请参见功能标志流程。
  3. 从代码库中移除对功能标志的所有引用，包括测试。
  4. 从存储库中移除该功能的 YAML 定义。

一旦上述 MR 合并，您应该：

  1. 使用 /chatops run feature delete some_feature 从所有环境中清理功能标志。
  2. 功能标志从代码库中移除后，关闭功能标志的推出问题。

清理 ChatOps

当功能门从代码库中移除后，功能记录仍然存在于部署该标志的数据库中。 一旦 MR 部署到所有环境，就可以删除该记录：

/chatops run feature delete <feature-flag-name> --dev --pre --staging --staging-ref --production

检查功能标志状态

您可以使用以下 ChatOps 命令查看功能标志的当前状态：

/chatops run feature get <feature-flag-name>

由于这是只读命令，您可以通过以下方式避免弄乱生产频道：

  • 在 #chat-ops-test Slack 频道中运行它
  • 将其作为直接消息发送给 ChatOps 机器人

此命令的结果将显示：

  • 功能标志是否存在
  • 其当前状态（启用/禁用）
  • 配置的任何百分比推出或基于行为者的门