排查功能标志方面的问题

本指南提供了诊断和解决 App Lifecycle Manager 功能标志常见问题的步骤。

SDK 和运行时评估

OpenFeature API 旨在实现最高安全性，绝不会抛出导致应用崩溃的错误。

症状：标志返回安全默认值

如果标志服务无法访问、提供程序不可用或标志配置错误，SDK 会返回代码中提供的所需默认值。

解决方法：

  1. 验证 OpenFeature 提供程序与 saasconfig.googleapis.com 端点之间的连接。
  2. 检查是否存在身份验证错误。确保服务帐号具有 roles/saasconfig.viewer。
  3. 验证 FLAGD_SOURCE_PROVIDER_ID 是否正确。

症状：评估结果意外

如果标志未返回预期变体，请执行以下操作：

解决方法：

  1. 检查 CEL 条件和评估上下文。
  2. 如果在条件检查期间上下文缺少必需属性，评估引擎会跳过该特定规则。
  3. 如果在基于百分比的分配期间缺少属性，评估会返回 INVALID_CONTEXT。

监控发布

监控功能标志发布涉及验证编排状态（发布是否完成？）和应用运行状况（二进制文件是否选择了标志？）。

发布编排状态

系统会实时监控操作的成功率。

自动暂停

为防止“损坏”的配置到达整个舰队，如果失败率超过错误预算（默认情况下，每个位置为 10%），系统会自动暂停发布。

查看汇总统计信息

使用 describe 命令查看汇总失败计数，并确定发布是 PAUSED 还是 FAILED。

gcloud beta app-lifecycle-manager rollouts describe ROLLOUT_ID --location=global

过滤失败的单元更新

确认存在失败后，您必须找到错过更新的特定单元。使用此过滤条件仅隔离特定区域中失败的标志更新：

gcloud beta app-lifecycle-manager unit-operations list \
    --location=LOCATION \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

诊断根本原因

对于每个失败的操作，您都可以检索执行引擎提供的详细错误消息。读取 state_message 字段。

gcloud beta app-lifecycle-manager unit-operations describe OPERATION_ID --location=LOCATION

单元缺少配置

了解单元固定

固定会将单元冻结在其当前版本，防止其被任何自动或手动发布更新。在固定期限到期或手动取消固定之前，固定单元会被明确排除在发布操作之外。

固定单元缺少配置

当在功能标志发布期间固定单元时，会出现一个关键场景。固定会阻止所有更新，这意味着单元会跳过接收其配置所需的 FlagUpdate 操作。

症状： 在取消固定单元并将其升级到需要功能标志的二进制文件后，应用无法初始化或进入无限重试循环，导致就绪探测失败和容器持续重启。

根本原因： UnitKind 的 default_flag_revisions 在单元固定期间未更新，导致单元没有有效配置。

诊断命令

1. 列出失败的标志操作

如需查找错过更新的单元，请按 UNIT_OPERATION_STATE_FAILED 状态和 flag_update 类型过滤单元操作。

gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

2. 专门过滤失败的标志发布

如需查明整个舰队或特定单元中失败的标志更新，请为 UNIT_OPERATION_STATE_FAILED 状态添加条件。

# Find all failed operations for a specific unit
gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="unit:UNIT_ID AND state:UNIT_OPERATION_STATE_FAILED"

3. 检查失败原因

使用 describe 命令读取 state_message。

gcloud beta app-lifecycle-manager unit-operations describe "OPERATION_ID" --location="LOCATION"

4. 检查单元条件

您还可以直接检查单元的当前状态。如果标志发布当前失败或上次操作导致错误，状态中会反映出来。类型为 operationError 的条件。

gcloud beta app-lifecycle-manager units describe "UNIT_ID" --location="LOCATION"

手动缓解措施

应用 UnitKind 默认标志修订版本

如果单元因在一个或多个发布期间被固定而缺少配置，您可以手动将单元重置为其 UnitKind 中定义的当前基准，从而恢复配置。

  1. 取消固定单元 （如果已固定）。
  2. 从父级 UnitKind 检索默认修订版本 。
  3. 创建包含这些修订版本的新 FlagRelease 。
  4. 手动启动 FlagUpdate 单元操作以应用恢复版本。
# 1. Unpin
gcloud beta app-lifecycle-manager units update "UNIT_ID" \
    --location="LOCATION" \
    --maintenance-pinned-until-time=""

# 2. Retrieve default revisions
gcloud beta app-lifecycle-manager unit-kinds describe "UNIT_KIND_ID" \
    --location="global" \
    --format="value(defaultFlagRevisions)"

# 3. Create recovery release
gcloud beta app-lifecycle-manager flags releases create "recovery-release-1" \
    --location="global" \
    --unit-kind="UNIT_KIND_ID" \
    --revisions="REVISIONS"

# 4. Initiate manual update
gcloud beta app-lifecycle-manager unit-operations create "recovery-op" \
    --unit="UNIT_ID" \
    --flag-release="recovery-release-1" \
    --location="global"