我們希望您提供有關功能標記功能和使用者體驗的意見回饋。如要登記意願，提供意見回饋並影響產品設計，請填寫這份表單。

排解功能旗標問題

本指南提供步驟，協助您診斷及解決 App Lifecycle Manager 功能旗標的常見問題。

SDK 和執行階段評估

OpenFeature API 的設計宗旨是確保安全性，絕不會擲回導致應用程式當機的錯誤。

問題：系統傳回安全預設值的旗標

如果無法連線至旗標服務、供應商無法使用，或旗標設定有誤，SDK 會傳回您在程式碼中提供的必要預設值。

解決方法：

確認 OpenFeature 提供者與 saasconfig.googleapis.com 端點之間的連線。
檢查是否有驗證錯誤。確認服務帳戶具備 roles/saasconfig.viewer。
確認 FLAGD_SOURCE_PROVIDER_ID 正確無誤。

問題：評估結果不如預期

如果旗標未傳回預期的變體：

解決方法：

檢查 CEL 條件和評估情境。
如果在條件檢查期間，內容缺少必要屬性，評估引擎會略過該特定規則。
如果以百分比為準的分配方式缺少屬性，評估結果會傳回 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 中定義的目前基準，藉此復原設定。

取消固定單元 (如果已固定)。
從父項 UnitKind 擷取預設修訂版本。
建立包含這些修訂內容的新 FlagRelease。
手動啟動 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"