이 가이드에서는 앱 수명 주기 관리자 기능 플래그의 일반적인 문제를 진단하고 해결하는 단계를 제공합니다.
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. 실패한 플래그 출시만 필터링
전체 Fleet 또는 특정 단위에서 실패한 플래그 업데이트를 정확히 파악하려면 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"