Vercel Flags 롤아웃 감사 가이드: 평가 메트릭과 CLI 버전 Diff로 검증하기

기능 플래그를 10%로 설정했다고 해서 실제 요청의 10%가 새 변형을 받는 것은 아닙니다. targeting rule, 직접 지정된 사용자, fallback, 잘못된 SDK key와 환경 설정이 결과를 바꿀 수 있습니다. 설정 변경 이력과 실제 평가 결과를 같은 시간축에서 확인해야 롤아웃을 검증할 수 있습니다.

Vercel은 2026년 7월 23일 Flags 상세 화면에 실시간 평가 메트릭을 추가했고, 같은 날 CLI에서 전체 revision 이력과 semantic diff를 확인할 수 있는 vercel flags versions 명령을 공개했습니다. 두 기능을 함께 사용하면 “무엇을 바꿨는가”와 “실제로 무엇이 제공됐는가”를 연결할 수 있습니다.

이 글에서는 두 기능을 점진적 롤아웃과 장애 대응 절차로 묶어 설명합니다.

새로 추가된 두 가지 관측 축

평가 메트릭

각 flag 상세 페이지에서 evaluations per minute을 시간에 따라 확인할 수 있습니다. 차트에는 flag version 변경 시점이 표시되므로, 설정 변경 직후 평가량이나 변형 분포가 어떻게 달라졌는지 비교할 수 있습니다.

평가 결과는 다음 차원으로 그룹화하거나 필터링할 수 있습니다.

variant
reason
environment
SDK key
client
reporting project

Custom client는 초기화 시 clientName을 설정해 별도 그룹으로 표시할 수 있습니다. @vercel/flags-core 1.6.0 이상으로 올리면 별도 계측 설정 없이 메트릭이 표시됩니다.

CLI 버전 이력과 semantic diff

vercel flags versions <flag>는 flag revision의 작성자, 변경 메시지, 시각, 변경된 environment를 출력합니다.

vercel flags versions checkout-redesign
vercel flags versions checkout-redesign --environment production

자동화나 감사 자료가 필요하면 JSON 출력과 pagination 옵션을 사용합니다.

vercel flags versions checkout-redesign \
  --environment production \
  --limit 100 \
  --json > checkout-redesign-versions.json

특정 revision과 바로 이전 revision의 차이는 semantic diff로 확인합니다.

vercel flags versions diff checkout-redesign --revision 42

이 diff는 단순 텍스트 차이가 아니라 targeting rule, rollout percentage, condition의 필드 수준 추가·삭제·수정을 보여줍니다.

롤아웃 검증은 세 질문으로 시작합니다

플래그 변경 후 다음 세 질문에 답할 수 있어야 합니다.

어떤 설정이 언제 바뀌었는가?
어떤 environment와 client가 어떤 variant를 받았는가?
예상과 다른 결과가 targeting, fallback, 잘못된 SDK key 중 무엇 때문인가?

버전 이력만 보면 첫 번째 질문에는 답할 수 있지만 실제 제공 결과는 알 수 없습니다. 평가 메트릭만 보면 분포는 보이지만 누가 어떤 설정을 바꿨는지 확인하기 어렵습니다. 두 자료를 같은 시간 범위로 맞춰야 원인을 좁힐 수 있습니다.

배포 전 기준선을 남깁니다

롤아웃을 시작하기 전에 현재 production revision을 저장합니다.

mkdir -p audit/flags/checkout-redesign

vercel flags versions checkout-redesign \
  --environment production \
  --limit 100 \
  --json \
  > audit/flags/checkout-redesign/before-versions.json

다음 정보도 변경 요청이나 배포 기록에 남깁니다.

대상 flag와 environment
기존 revision과 변경 예정 revision
예상 variant 비율
targeting 대상과 제외 대상
fallback variant
rollout 시작·중단 조건
담당자와 rollback 결정권자

“10%로 올린다”보다 “production의 enterprise 제외 사용자에게 new-checkout을 10% 제공하고, 오류율 상승 또는 fallback 급증 시 이전 revision으로 되돌린다”처럼 기록해야 검증할 수 있습니다.

설정 변경 직후에는 전체 트래픽보다 차원을 분리합니다

평가 메트릭에서 전체 evaluations per minute만 보면 정상처럼 보일 수 있습니다. 먼저 다음 순서로 범위를 줄입니다.

1. Environment

Production, Preview, Development를 분리합니다. Preview에서만 검증하려던 SDK key가 production 요청에 사용되거나 반대 상황이 생기지 않았는지 확인합니다.

2. SDK key와 reporting project

여러 프로젝트가 한 flag를 평가하면 예상보다 많은 트래픽이 보일 수 있습니다. SDK key와 reporting project로 그룹화해 어떤 애플리케이션이 평가를 발생시키는지 확인합니다.

3. Client

웹, API, background worker가 같은 flag를 사용한다면 clientName으로 구분합니다. 한 client만 오래된 설정이나 다른 fallback을 사용하는 문제를 빠르게 찾을 수 있습니다.

4. Reason

Vercel Flags는 environment 설정을 선택한 뒤 direct target, 위에서 아래 순서의 rule, fallback outcome을 평가합니다. 따라서 결과 비율이 예상과 다르면 reason을 통해 다음을 구분해야 합니다.

특정 사용자가 direct target으로 고정됨
앞선 rule이 뒤의 percentage rollout보다 먼저 일치함
evaluation context가 부족해 fallback으로 내려감
environment가 paused 상태이거나 고정 variant를 제공함

5. Variant

마지막으로 variant 분포를 봅니다. percentage rollout은 충분한 평가 표본과 일관된 evaluation context가 있어야 의도한 비율에 가까워집니다. 짧은 시간의 작은 요청 수만 보고 정확히 10%여야 한다고 판단하지 않습니다.

Version marker와 메트릭 변화를 연결합니다

평가 차트에 표시된 version 변경 지점을 기준으로 전후를 비교합니다.

관측 패턴	가능한 원인	먼저 확인할 것
새 revision 직후 fallback 증가	context 누락 또는 rule 조건 불일치	reason, client, SDK key
특정 project에서만 이전 variant 유지	오래된 SDK key나 배포	reporting project, environment
rollout 비율보다 direct target이 많음	직접 대상이 percentage rule보다 우선	targeting configuration
전체 평가량 급증	중복 평가 또는 새 client 유입	client, evaluations per request
revision 변경 없이 분포 변화	애플리케이션 context나 트래픽 구성 변화	배포 시각, client, user segment

중요한 점은 상관관계를 인과관계로 바로 단정하지 않는 것입니다. Flag version marker와 변화 시각이 겹쳐도 같은 시각의 애플리케이션 배포, 마케팅 유입, background job 증가가 영향을 줄 수 있습니다.

Semantic diff를 변경 승인 자료로 사용합니다

사람이 dashboard 화면을 눈으로 비교하면 rule 순서, percentage, 조건 연산자의 작은 차이를 놓치기 쉽습니다. 변경 후 revision 번호를 확보하고 semantic diff를 저장합니다.

vercel flags versions diff checkout-redesign --revision 42 \
  > audit/flags/checkout-redesign/revision-42.diff

리뷰에서는 다음 항목을 확인합니다.

production 외 environment가 함께 바뀌지 않았는가
기존 direct target이 제거되지 않았는가
rule 순서가 달라지지 않았는가
percentage와 served variant가 의도와 일치하는가
condition의 entity, attribute, operator가 맞는가
변경 메시지가 작업 티켓과 연결되는가

이 파일은 “현재 설정 전체”보다 “이번 변경이 무엇인지”를 검토하는 데 적합합니다.

자동화에서는 읽기와 쓰기를 분리합니다

Vercel CLI는 flag 생성, 활성화, 비활성화, targeting rule과 segment 변경까지 지원합니다. 그러나 감사 봇이나 AI 에이전트가 조사와 수정 권한을 동시에 가지면, 진단 과정에서 상태를 바꿀 위험이 있습니다.

권장 구조는 다음과 같습니다.

Read-only audit job
  ├─ versions --json 수집
  ├─ versions diff 생성
  ├─ 평가 메트릭 검토
  └─ 변경 제안 작성

Approval
  └─ 담당자가 대상 environment와 revision 확인

Permissioned write job
  └─ 승인된 변경만 적용

자동화용 SDK key와 운영자가 사용하는 관리 자격 증명도 분리합니다. 평가용 SDK key는 flag 값을 읽는 용도이고, CLI 관리 권한과 같은 것으로 취급하면 안 됩니다.

Rollback은 “이전 상태 복원”과 “원인 제거”를 구분합니다

Vercel Dashboard의 Activity에는 변경 작성자, 시각, 수정 내용이 기록되며 이전 configuration을 Restore할 수 있습니다. Restore는 기존 revision을 지우는 것이 아니라 복원 작업 자체를 새 변경으로 남깁니다.

문제가 발생했을 때는 다음 순서가 안전합니다.

영향받는 environment와 client를 메트릭으로 좁힙니다.
현재 revision과 직전 revision의 semantic diff를 확인합니다.
즉시 완화가 필요하면 dashboard에서 검증된 configuration을 복원합니다.
복원 직후 평가 메트릭에서 fallback과 variant 분포가 정상화되는지 확인합니다.
애플리케이션 코드와 evaluation context의 원인을 별도로 수정합니다.

설정 복원만으로 문제가 해결되지 않으면 배포 코드, SDK key, context 생성 로직에 원인이 있을 가능성이 큽니다.

평가량은 사용자 수나 비즈니스 성과가 아닙니다

Evaluations per minute은 flag가 평가된 횟수를 보여줍니다. 다음과 동일하지 않습니다.

고유 사용자 수
페이지뷰
전환 수
성공한 요청 수
variant별 매출 또는 오류율

한 요청에서 같은 flag를 여러 번 평가하거나 background worker가 반복 평가하면 평가량이 늘 수 있습니다. 사용자 행동과 성과를 보려면 Web Analytics의 custom event나 애플리케이션 메트릭을 함께 사용해야 합니다.

권장 관측 구조는 다음과 같습니다.

데이터	답하는 질문
Flag evaluation metrics	어떤 variant가 어떤 reason·client·environment에서 제공됐는가
CLI version history	누가 언제 어떤 설정을 바꿨는가
Semantic diff	이번 revision에서 어떤 rule과 percentage가 달라졌는가
Application logs	evaluation context와 요청 처리 결과는 무엇인가
Web Analytics·제품 지표	variant가 사용자 행동과 성과에 어떤 영향을 줬는가

단계적 롤아웃 절차

1. Preview 검증

Preview SDK key와 reporting project를 확인합니다.
내부 사용자나 테스트 entity를 direct target으로 지정합니다.
reason과 variant가 예상대로 보이는지 확인합니다.

2. Production 소수 대상

production 변경 전 versions JSON을 저장합니다.
제한된 direct target 또는 작은 percentage로 시작합니다.
version marker 이후의 variant, reason, client를 확인합니다.

3. 확대

각 확대 단계마다 revision diff를 보존합니다.
오류율·latency·제품 지표와 flag 평가를 같은 시간 범위로 비교합니다.
예상하지 않은 fallback이나 오래된 client가 없을 때만 다음 단계로 이동합니다.

4. 완료와 정리

rollout을 완료한 뒤 flag가 코드에서 더 이상 필요한지 판단합니다.
코드 제거 전에는 즉시 삭제하지 않습니다.
사용이 끝난 flag는 먼저 archive해 configuration과 history를 보존합니다.

감사 체크리스트

결론

안전한 feature flag 운영은 설정 화면에서 percentage를 바꾸는 것으로 끝나지 않습니다. CLI 버전 이력으로 변경 사실을 남기고, 평가 메트릭으로 실제 제공 결과를 확인하고, 제품 지표로 영향을 검증하는 세 단계가 필요합니다.

롤아웃마다 변경 전 JSON, revision diff, 평가 메트릭의 version marker를 남기면 문제가 생겼을 때 “누가 무엇을 바꿨는지”와 “어떤 요청이 영향을 받았는지”를 빠르게 연결할 수 있습니다.