Statsig 입문 3편 — Feature Flags 깊이 · Targeting · Rollout · Holdout

이 글은 Statsig 입문에서 운영까지 시리즈 3편이에요. 1편 종합 소개 · 2편 SDK Quickstart 까지 코드 한 줄로 분기되는 첫 gate 를 박았다면, 이번 3편은 그 gate 를 진짜 운영 도구로 키우는 자리.

이번 글의 범위

2편 끝에서 박은 단순 ON/OFF gate 는 50% 사용자에게만·특정 국가만·VIP 사용자만 같은 복잡한 운영 조건 을 표현 못 해요. 3편은 이걸 실전 가능한 도구 로 키우는 자리:

• Targeting Rules (대상 사용자 결정 규칙) 의 순차 평가 메커니즘
• 6 카테고리의 Conditions (조건)
• Stability (안정성) · Resalting (재무작위화)
• 환경 분리 · Scheduled Rollouts (예약 단계 배포)
• Dependent Gates (gate 계층) · Built-in A/B
• Override (강제 우회) · Audit Log (변경 이력) · 라이프사이클

Feature Gate 의 진짜 운영 — 단순 ON/OFF 이상

Feature Gate 는 코드 분기 한 줄을 켜고 끄는 boolean 토글. 1편의 3 유형 분기 에서 본 것처럼, gate 가 boolean 반환 이라도 어떤 사용자에게 true 인가 의 결정 로직이 운영의 핵심. 단순 모두 ON / 모두 OFF 가 아니라 VIP 등급만·한국 + iOS 만·5% 만·지난주 가입자만·Chrome 100+ 만·experiment B 그룹만 같은 조건을 코드 한 줄도 안 건드리고 대시보드에서 표현하는 게 Feature Flag 의 진짜 가치.

Feature Gate 의 6단계 운영 흐름

Feature Gates 는 새 코드 배포 없이 실시간으로 제품 동작을 전환 하는 도구. — 공식 docs

운영 환경에서 gate 의 라이프사이클 은 6 단계예요.

→ 단계 1·2 까지는 2편에서 봤어요. 3편은 3~6 단계의 실전.

Targeting Rules — gate 의 두뇌

Targeting Rules 는 어떤 사용자에게 gate 를 적용할지 결정하는 규칙 묶음. Feature Gate 의 targeting 은 여러 rules 의 순차 리스트. 사용자가 들어오면 위에서 아래로 rule 평가.

순차 평가 (Sequential Evaluation)

Rule 1: "VIP 사용자" — 조건: tier = "vip" — Pass: 100%
Rule 2: "한국 사용자 일부" — 조건: country = "KR" — Pass: 50%
Rule 3: "Everyone" — Pass: 5%  (default catch-all)

여기서 시험 함정이 하나 있어요 — 사용자가 한 rule 의 조건을 만족하면, 그 다음 rule 은 평가 X. 위 예시에서 VIP 한국 사용자 가 들어오면 Rule 1 의 100% Pass 가 적용, Rule 2 의 50% 조건은 안 검사.

→ rule 순서가 결과를 결정. 일반적으로 좁은 조건 을 위에, 넓은 조건 을 아래에 배치.

Pass Percentage — 조건 만족 후 비율

각 rule 의 Pass % = 그 rule 의 조건을 만족한 사용자 중 얼마나 ON 인가. 100% = 무조건 ON, 50% = 절반만 ON.

Everyone 조건 — catch-all

마지막 rule 로 Everyone 을 두면 위 rule 들과 안 맞는 모든 사용자 가 대상. Pass % 를 0% (= 기본 OFF) 또는 2% (= 모니터링 용 점진 rollout) 등.

Stability — 같은 사용자 = 같은 결과

평가는 unitID 를 기준으로 안정적. 50% 롤아웃에서 통과하는 사용자는 항상 통과. — 공식 docs

Statsig 의 deterministic hashing (사용자 ID 를 결정적으로 해시해 항상 같은 결과를 내는 방식) — 같은 userID + gate name = 같은 결과. 사용자가 어떤 변형을 봤다면, 다음에도 같은 변형.

checkGate(user1, "new_flow")  // 항상 true
checkGate(user1, "new_flow")  // 다시 호출해도 true
checkGate(user2, "new_flow")  // user2 는 false 일 수도

UX 일관성 + 측정 가능한 실험 의 기반.

Resalting — 무작위화 리셋

Resalting = 해시 salt 값을 바꿔 사용자 그룹을 다시 무작위로 섞는 동작. 같은 gate 의 Pass % 를 변경해도 기존 사용자 분포 유지. 만약 완전히 새 random 할당 이 필요하면 Resalting 으로 salt 값 변경 → hashing 새로 시작.

언제 — 새 실험 시작 · 데이터 오염 의심 시. 일상 변경에서는 X.

Conditions — 6 카테고리

Conditions = rule 안에서 사용자 속성을 검사하는 조건문. Statsig 의 조건 종류가 풍부해요. 6 카테고리로 분류 가능.

카테고리 1: 사용자 식별

조건: Email contains any of: "@statsig.com", "@example.com"
→ 회사 직원만 대상

카테고리 2: 기기·브라우저

조건: App Version < 3.0
→ 구버전 사용자 제외 (또는 강제 업데이트 표시)

카테고리 3: 지역·네트워크

조건: Country any of: "KR", "JP", "VN"
→ 동아시아 지역 한정 rollout

카테고리 4: 환경·시간

조건: Environment Tier any of: "staging", "development"
→ staging/dev 환경만 ON (production OFF)

조건: Time after "2026-05-20 09:00 KST"
→ 5월 20일 이후 자동 활성

카테고리 5: Gate·Segment 연계

조건: User Passes Target Gate "beta_tester"
→ beta tester gate 통과한 사용자만

Segment = 재사용 가능한 사용자 그룹 정의. VIP 사용자 세그먼트 한 번 정의 → 여러 gate 에서 재사용.

카테고리 6: Custom·Private 속성

조건: Custom.tier any of: "premium", "enterprise"
조건: Custom.signupYear >= 2025
조건: Private.ssn is null  (민감 데이터 — 로그 안 남음)

여기서 시험 함정이 하나 있어요 — Custom 속성을 user object 에 박을 때 어떤 SDK 든 일관 해야. Server 가 tier: "vip", Client 가 userTier: "vip" 면 다른 사용자로 인식. 2편의 user factory 패턴이 그래서 중요.

Operator 의 다양성

각 condition 의 operator 가 풍부해서 equality (any of · none of), string (contains · regex), number (> · >= · < · <=), null check (is null · is not null), time (after · before) 까지 — SQL WHERE 절과 유사한 표현력.

AND vs OR — 조건 조합

한 rule 안 여러 조건 = AND (모두 만족해야 통과).

Rule "한국 VIP iOS":
  조건 1: Country = "KR"            (AND)
  조건 2: Custom.tier = "vip"       (AND)
  조건 3: OS = "iOS"
→ 셋 다 만족하는 사용자만

OR 효과 = 여러 rule 로 분리. 각 rule 이 독립적으로 매칭.

자동 추론 속성 — 코드 안 박아도 자동

클라이언트 SDK 는 IP, User Agent, 앱 버전, 로케일을 자동 으로 감지. — 공식 docs

자동 추론 항목은 Browser (User Agent 에서), OS·Device Model, IP, Country (IP 기반 lookup), Locale — user object 에 명시 안 박아도 자동 인식. 단:

• 서버 사이드 SDK = req 의 IP 직접 전달 필요
• 모바일 SDK = 디바이스 정보 자동, but 일부 필드는 명시 권장
• Privacy 민감 = IP/Country 가 추적 동의 필수 인 지역

환경 분리 — Production · Staging · Development

2편의 environment 옵션 의 응용.

// app start
const statsig = new Statsig(SDK_KEY, {
  environment: process.env.NODE_ENV  // "production" | "staging" | "development"
});

이러면 gate rule 에서:

Rule "Dev/Staging 만":
  조건: Environment Tier any of: "staging", "development"

→ 같은 코드, 환경별 다른 동작. production 에 영향 없이 staging 에서 새 flow 테스트.

운영 패턴 — 환경 게이팅

Rule 1: Dev/Staging 환경 → 100% ON  (개발자 검증)
Rule 2: Production VIP → 50% ON     (점진적 prod rollout)
Rule 3: Everyone → 0% OFF           (default 안전)

3 단 rule = 환경별 점진 활성.

Scheduled Rollouts — 시간 기반 자동 단계

Scheduled Rollouts = 시간 기반 단계적 배포. — 공식 docs

Scheduled Rollouts 는 사전 시간표대로 Statsig 가 자동 단계 변경하는 기능 — 대시보드 클릭 없이도 rollout 비율이 자동으로 올라가요.

2026-05-20 09:00 → 5% rollout
2026-05-22 09:00 → 25%
2026-05-25 09:00 → 50%
2026-05-30 09:00 → 100%

→ 주말·휴일 자동 진행 · 팀 일정 무관. 운영자의 손이 덜 가는 표준 패턴.

Time 조건과의 차이

단순 오늘 9 AM 부터 ON = Time condition. 주 단위 점진 rollout = Scheduled Rollouts.

Dependent Gates · Holdouts — gate 의 계층 관계

여기서 정말 강력한 자리 — gate 가 다른 gate 에 의존. Dependent Gates = 상위 gate 통과 여부를 조건으로 거는 하위 gate.

Chained Dependencies

gate "Premium Feature" 의 rule:
  조건: User Passes Target Gate "feature_alpha"
       AND Custom.tier = "premium"

→ 상위 gate 가 OFF 면 하위 gate 도 OFF. 글로벌 kill switch 의 표준 패턴.

Holdouts — 실험 control 보존

Holdout = Statsig 의 실험에 영구히 참여 안 함 인 사용자 그룹. 순수 control 측정용.

gate "all_new_features" — Pass: 95%
  → 95% 사용자가 새 기능들 받음
  → 5% (holdout) = 어떤 새 기능도 받지 않음

이 5% 가 오래된 baseline. 모든 새 기능의 순효과 측정 의 기준. 제품 전체 progress 측정 의 표준.

실전 holdout 패턴

Top-level: "global_holdout" — Pass: 95%

각 새 기능 gate:
  Rule 1: "Passes global_holdout" → AND 추가 조건
  → holdout 5% 는 *모든 새 기능 OFF*

분기점 — 모든 새 기능 이 holdout 5% 를 제외하고 운영. 1년 후 holdout 5% 의 retention/매출 과 95% 의 retention/매출 비교 = 그 1년 동안의 모든 기능 효과.

Built-in A/B — gate 의 자동 실험 효과 측정

Feature Gate 가 그냥 ON/OFF 만 하는 게 아니라 자동 A/B 분석 도 함.

Built-in A/B Testing: Pulse 를 활용한 간단한 A/B 테스트. — 공식 docs

Pulse 는 Statsig 의 내장 실험 분석 엔진. 작동하면 gate 의 Pass 그룹 과 Fail 그룹 을 통계적으로 비교, 사용자 행동 메트릭(event 로깅 기반)의 그룹별 차이 를 보고 p-value · CI 를 자동 계산해요.

→ gate 켜기만 해도 "새 flow 가 결제율 5% 올렸는가?" 자동 분석. 별도 experiment 설정 안 해도 효과 측정.

실험과의 차이

→ Gate = 느슨한 검증, Experiment = 엄격한 검증. 4편에서 깊게.

Override — 안전선

Override = targeting rule 을 무시하고 특정 사용자를 강제로 통과/실패시키는 메커니즘.

사용 case

QA 사용자는 gate 의 targeting rule 무시 하고 항상 ON 으로 테스트, VIP 는 점진적 rollout 이라도 즉시 ON 으로 우대, CEO 데모 직전엔 해당 user ID 만 ON 으로 안전한 시연 — 이런 식으로 쓰여요.

Override 설정

console 에서 gate detail → Overrides → user ID 리스트 추가.

함정 — Override 사용자는 분석 제외

Override 로 Pass/Fail 리스트에 추가된 사용자는 분석 제외. — 공식 docs

→ Built-in A/B 통계에서 제외. 공식 측정에 노이즈 안 됨.

운영 권장

Override 는 임시 수단 (QA·데모). 영구 ON 이 필요하면 targeting rule 의 User ID 조건을 쓰는 게 맞아요.

Audit Log · 협업 — 운영의 안전

Audit Log = 모든 gate 변경(누가·언제·무엇)을 기록한 이력.

자주 만나는 case

원인 모를 prod 영향 이 보이면 audit log 에서 최근 gate 변경 을 먼저 확인하고, Statsig Enterprise 라면 변경 승인 워크플로 로 변경 전 approval 을 의무화할 수 있어요. 팀 협업 측면에선 gate 별 owner + comment 가 표준.

통합

• Slack 알림 — gate 변경 시 채널에 publish
• Webhook — 사내 audit 시스템 연동
• 2-person rule — production 변경은 2명 이상 승인 (Enterprise)

Gate 라이프사이클 — temporary vs permanent

여기서 시험 함정 하나 — gate 생성은 쉬운데, gate cleanup 이 어렵다.

Temporary Gate

gate "new_checkout_flow_v2"
→ rollout 100% 도달 후
→ 코드에서 if 문 제거
→ gate 도 archived 처리

일시 gate — 기능 GA 완료 후 제거 권장. 수개월 누적 시 코드 안 if 문 100개+, console gate 200개+ 가 됨.

Permanent Gate

gate "emergency_kill_switch"
→ 항상 ON 유지
→ 비상시 OFF (긴급 차단기)

영구 gate — kill switch · 지역별 기능 제어 · 장기 비즈니스 룰. 제거 X.

표시 명시

Gate 생성 시 temporary / permanent 태그를 박고, temporary 는 N 일 후 archive 알림 을 받고, 팀 분기별 cleanup 작업 으로 정리해요.

자주 만나는 사고 — Feature Flag 운영

사고 1: Rule 순서 잘못 → 의도 다른 결과

원인 — VIP 만 100% rule 이 Everyone 5% rule 보다 아래에 배치. VIP 사용자도 5% 만 ON.

해결 — 좁은 조건을 위, 넓은 조건을 아래 원칙. UI 의 drag and drop 으로 순서 명시.

사고 2: AND 와 OR 혼동

원인 — 한 rule 의 3 조건 모두 AND 인데 OR 의도 였음 → 거의 0 사용자.

해결 — OR 효과 = 별도 rule 로 분리. 또는 Segment 활용.

사고 3: Custom 속성 type mismatch

원인 — Custom.signupYear 가 어떤 곳은 string "2025", 어떤 곳은 int 2025. 조건 >= 2025 가 일관 안 됨.

해결 — user object schema 통일 (TypeScript · Python dataclass).

사고 4: Override 가 영구화

원인 — QA 용 Override 가 제거 안 됨 → 1년 후 모든 QA 가 production 새 기능.

해결 — Override 의 expiration date 설정 · 분기별 cleanup.

사고 5: Resalting 잘못 호출 → 사용자 그룹 흩어짐

원인 — 기존 50% rollout 의 salt 변경 → 기존 ON 사용자 절반이 갑자기 OFF. UX 혼란.

해결 — Resalting 은 새 실험 시작 등 명확한 의도 에만. 기존 rollout 변경엔 X.

사고 6: Time condition 의 timezone

원인 — Time after "2026-05-20 09:00" 가 UTC 인지 KST 인지 모호.

해결 — UTC ISO 형식 명시 (2026-05-20T00:00:00Z). console 에서도 timezone 표시.

사고 7: Holdout 너무 큼

원인 — holdout 20% → 프로덕션 매출 손실 큼.

해결 — 5~10% 가 표준. 의미 있는 통계 + 비즈니스 손실 최소.

운영 권장 패턴

Pattern 1: 표준 점진 rollout

Rule 1: "Internal team" — Email contains "@statsig.com" — 100%
Rule 2: "Production rollout" — Environment "production" — 5%
Rule 3: "Everyone" — 0%

내부 → 5% production → 점진 증가 → 100%.

Pattern 2: Segment 재사용

Segment "vip_users":
  Custom.tier = "premium" OR Custom.tier = "enterprise"

Gate A: Rule "VIP only" — User in Segment "vip_users" — 100%
Gate B: Rule "VIP only" — User in Segment "vip_users" — 100%

여러 gate 에서 같은 그룹 정의 재사용. 한 곳 변경 → 모든 gate 반영.

Pattern 3: Holdout + 측정

Top-level: "global_holdout" — 5% Fails

Gate A: Rule "Passes global_holdout" + Pass 50% → 47.5% 실제 ON
Gate B: Rule "Passes global_holdout" + Pass 100% → 95% 실제 ON

holdout 5% 가 모든 새 기능 OFF → 장기 baseline.

Pattern 4: Scheduled Rollouts + Kill switch

Gate "feature_x":
  Scheduled Rollouts:
    2026-05-20 → 5%
    2026-05-22 → 25%
    2026-05-25 → 50%
    2026-05-30 → 100%

Gate "feature_x_kill_switch" (permanent):
  Rule 1: Everyone — 100%   (default ON = kill switch OFF)

자동 rollout + 언제든 kill switch OFF = 즉시 차단.

Pattern 5: 환경별 차별

Environment "development" → 100% ON  (개발자 자유)
Environment "staging"     → 100% ON  (QA 검증)
Environment "production"  → 5% Scheduled Rollouts (점진)

각 환경 완전 분리 + production 안전선.

Pattern 6: Temporary 명시 + 자동 archive

Gate metadata:
  type: "temporary"
  expires: "2026-08-01"
  owner: "checkout-team"
  cleanup_after_GA: true

3개월 뒤 자동 알림 → cleanup 작업.

시험 직전 한 번 더 — Feature Flag 깊이 함정 압축 노트

• Feature Gate = boolean 토글, 단순 ON/OFF 이상의 targeting 이 핵심
• 6단계 운영 흐름 = 생성 → SDK → 테스트 → Override → 모니터링 → 라이프사이클
• Targeting Rules = 여러 rule 의 순차 리스트
• 순차 평가 — 한 rule 만족하면 다음 rule 평가 X
• 좁은 조건을 위, 넓은 조건을 아래 원칙
• Pass % = rule 의 조건 만족 후 ON 비율
• Everyone = catch-all rule (마지막)
• Stability = unitID 기준 deterministic — 같은 사용자 = 같은 결과
• Resalting = salt 변경 → 새 random 할당 (일상 변경 X)
• 6 Conditions 카테고리:
• 사용자 식별 (User ID · Email · Unit ID)
• 기기·브라우저 (Browser · App Version · OS · Device Model)
• 지역·네트워크 (Country · IP)
• 환경·시간 (Environment Tier · Time)
• Gate·Segment 연계 (Passes Gate · in Segment)
• Custom·Private (Custom Field · Private Attributes)
• Operator 풍부 — any of · contains · >= · regex · is null · before/after
• AND vs OR — 한 rule 안 = AND, 여러 rule = OR
• 자동 추론 — Browser · OS · IP · Country · Locale (client SDK 자동)
• 서버 SDK = IP 명시 전달 권장
• Private Attributes = 로깅 안 됨 (PII 안전)
• 속성 우선순위 = top-level > custom > privateAttributes
• 환경 분리 = production · staging · development → environment 옵션 + rule 조건
• Scheduled Rollouts = 시간 기반 자동 다단계 rollout
• vs Time condition — Scheduled = 다단계, Time = 단일 시점
• Dependent Gates = Passes Target Gate 로 gate 계층
• Holdout = 영구 모든 새 기능 OFF 그룹 (5~10% 표준)
• holdout = 장기 baseline · 제품 progress 순효과 측정
• Built-in A/B = gate 가 자동으로 Pass/Fail 그룹 통계 비교 (Pulse)
• vs 정식 Experiment — 느슨한 검증 vs 엄격한 검증
• Override = 특정 사용자 강제 ON/OFF (QA · 데모)
• Override 사용자 = 분석 제외 (노이즈 X)
• Override 는 임시 수단, 영구는 targeting rule
• Audit Log = 모든 변경 기록 (who · when · what)
• Slack · webhook · 2-person rule (Enterprise)
• 라이프사이클 — Temporary vs Permanent
• Temporary = GA 후 archive (코드·console cleanup)
• Permanent = kill switch · 지역별 · 비즈니스 룰
• 함정 — rule 순서 (VIP 가 Everyone 아래)
• 함정 — AND vs OR 혼동 (OR 효과는 별도 rule)
• 함정 — Custom 속성 type mismatch (schema 통일)
• 함정 — Override 영구화 (expiration 설정)
• 함정 — Resalting 잘못 호출 (UX 혼란)
• 함정 — Time condition timezone (UTC ISO 권장)
• 함정 — Holdout 너무 큼 (5~10% 표준)
• 패턴 — 표준 점진 rollout (Internal → Production → Everyone)
• 패턴 — Segment 재사용 (정의 한 번 + 여러 gate)
• 패턴 — Holdout + Top-level gate
• 패턴 — Scheduled Rollouts + Kill switch 결합
• 패턴 — 환경별 차별 (dev/staging 자유, prod 점진)
• 패턴 — Temporary 명시 + 자동 archive

공식 문서: Feature Flags Overview · Feature Flag Conditions 에서 원문을 확인할 수 있어요.

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 1편 — 통합 플랫폼 종합 (Feature Flag · 실험 · 분석 · Infra)
• 2편 — SDK Quickstart · 30분 첫 Feature Gate

다음 글:

• 4편 — Experiments 깊이 · RCT · Allocation · 통계 함정
• 5편 — Product Analytics 깊이 · 6 차트 · Funnel · Retention
• 6편 — Warehouse Native 깊이 · Snowflake · BigQuery · dbt 결합
• 7편 — CDP · Slack · MCP · Webhook 운영 통합
• 8편 — Session Replay · Web Analytics · Infra Analytics