機能フラグの機能とユーザーエクスペリエンスに関するフィードバックをお待ちしております。フィードバックを送信してプロダクト設計に影響を与えるには、こちらのフォームに記入して、ご興味をお寄せください。

フィーチャートグルのトラブルシューティング

このガイドでは、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

Unit Missing Configs

ユニットの固定について

固定すると、ユニットは現在のリリースでフリーズされ、自動または手動のロールアウトによって更新されなくなります。固定されたユニットは、固定期間が終了するか、手動で固定が解除されるまで、ロールアウトオペレーションから明示的に除外されます。

固定されたユニットに設定がない

重大なシナリオは、フィーチャートグルのロールアウト中にユニットが固定された場合に発生します。固定するとすべての更新がブロックされるため、ユニットは構成の受信に必要な FlagUpdate オペレーションをスキップします。

現象: ユニットのピン留めが解除され、機能フラグを必要とするバイナリにアップグレードされた後、アプリケーションの初期化に失敗するか、無限の再試行ループに入り、readiness プローブの失敗とコンテナの継続的な再起動が発生します。

根本原因: ユニットが固定されている間、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. Check Unit Condition（ユニットの状態を確認）

ユニットの現在の状態を直接確認することもできます。フラグのロールアウトが現在失敗している場合や、最後のオペレーションでエラーが発生した場合は、ステータスに反映されます。タイプが operationError の条件。

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

手動による緩和策

UnitKind のデフォルトフラグリビジョンを適用する

1 つ以上のロールアウト中に固定されたために構成が欠落しているユニットがある場合は、ユニットを 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"