hgzero/rag/docs/basic_tier_workaround.md

Event Hub Basic Tier 제약사항 및 해결 방법

현재 상황

Event Hub Namespace: hgzero-eventhub-ns
Resource Group: rg-digitalgarage-02
Location: koreacentral
Tier: Basic ⚠️
Status: Active

Basic Tier 제약사항

기능	Basic	Standard	Premium
Consumer Groups	1개만 ($Default)	최대 20개	최대 100개
파티션	최대 32개	최대 32개	최대 100개
메시지 보존	1일	7일	90일
Capture	❌	✅	✅
가격	낮음	중간	높음

Basic Tier에서는 $Default Consumer Group만 사용할 수 있습니다.

---

해결 방법

방법 1: Tier 업그레이드 (권장) ⭐️

Event Hub를 Basic → Standard로 업그레이드하면 최대 20개의 Consumer Group 사용 가능

업그레이드 방법

Azure Portal:

1. Event Hub Namespace (hgzero-eventhub-ns) 페이지로 이동
2. 왼쪽 메뉴에서 "Pricing tier" 클릭
3. "Standard" 선택
4. "Apply" 버튼 클릭
5. 약 1-2분 후 적용 완료

Azure CLI:

az eventhubs namespace update \
  --resource-group rg-digitalgarage-02 \
  --name hgzero-eventhub-ns \
  --sku Standard \
  --capacity 1

비용:

• Basic: $0.015/시간 ($11/월)
• Standard: $0.03/시간 ($22/월)
• 차이: 약 $11/월 추가

장점:

• ✅ 여러 Consumer Group 사용 가능
• ✅ 메시지 보존 기간 7일로 증가
• ✅ Capture 기능 사용 가능
• ✅ 영구적 해결책

단점:

• ❌ 비용 증가 (약 2배)
• ❌ 관리자 승인 필요할 수 있음

---

방법 2: $Default Consumer Group 공유 사용 (임시)

개발/테스트 시 기존 프로덕션 Consumer를 잠시 중지하고 테스트

실행 순서

Step 1: 프로덕션 Consumer 중지

# 기존 Consumer 프로세스 확인
ps aux | grep "start_consumer.py" | grep -v grep

# PID 확인 후 종료
kill <PID>

# 예시
kill 51257

Step 2: 테스트 Consumer 실행

cd /Users/daewoong/home/workspace/HGZero/rag
python start_consumer.py

Step 3: 테스트 완료 후 프로덕션 재시작

# Ctrl+C로 테스트 Consumer 종료

# 프로덕션 Consumer 재시작
python start_consumer.py &

장점:

• ✅ 추가 비용 없음
• ✅ 즉시 테스트 가능
• ✅ 권한 불필요

단점:

• ❌ 프로덕션 서비스 중단
• ❌ 동시 실행 불가
• ❌ 임시 방법

주의사항:

• ⚠️ 프로덕션 환경에서만 사용 중이라면 비추천
• ⚠️ 업무 시간 외에만 테스트
• ⚠️ 테스트 후 반드시 프로덕션 재시작 확인

---

방법 3: Checkpoint 위치 변경으로 독립 실행

동일한 Consumer Group을 사용하되, checkpoint 저장 위치를 다르게 하여 독립적으로 실행

구현 방법

Step 1: 별도 Storage Container 생성

Azure Portal:

1. Storage Account (hgzerostorage) 접속
2. "Containers" 클릭
3. "+ Container" 클릭
4. 이름: hgzero-checkpoints-dev
5. Create

Step 2: config_dev.yaml 생성

# config_dev.yaml
eventhub:
  connection_string: ${EVENTHUB_CONNECTION_STRING}
  name: ${EVENTHUB_NAME}
  consumer_group: "$Default"  # 동일
  storage:
    connection_string: ${AZURE_STORAGE_CONNECTION_STRING}
    container_name: "hgzero-checkpoints-dev"  # 다른 컨테이너!

# 나머지는 config.yaml과 동일

Step 3: 개발용 Consumer 실행 스크립트

# start_dev_consumer.py
import asyncio
from pathlib import Path

from src.utils.config import load_config
from src.db.rag_minutes_db import RagMinutesDB
from src.db.postgres_vector import PostgresVectorDB
from src.utils.embedding import EmbeddingGenerator
from src.services.eventhub_consumer import start_consumer

async def main():
    # 개발용 설정 파일 로드
    config_path = Path(__file__).parent / "config_dev.yaml"
    config = load_config(str(config_path))

    # ... 나머지는 start_consumer.py와 동일

if __name__ == "__main__":
    asyncio.run(main())

Step 4: 실행

# Terminal 1: 프로덕션 Consumer
python start_consumer.py

# Terminal 2: 개발 Consumer (다른 checkpoint)
python start_dev_consumer.py

장점:

• ✅ 동시 실행 가능
• ✅ 독립적인 checkpoint
• ✅ 추가 비용 거의 없음 (Storage만)
• ✅ Tier 업그레이드 불필요

단점:

• ❌ 동일 파티션을 두 Consumer가 읽으려 하면 ownership 경쟁
• ❌ 한쪽만 이벤트 수신 (ownership을 가진 쪽)
• ❌ 완전한 독립 실행은 아님

결론:

• 이 방법은 checkpoint만 독립이고, 여전히 ownership 경쟁 발생
• 동시 실행은 불가능
• 권장하지 않음 ❌

---

방법 4: 로컬 개발 환경에서만 테스트

Event Hub 대신 로컬 메시지 큐 사용

옵션 A: Azure Event Hub Emulator (권장)

현재는 공식 Emulator가 없으므로, Kafka나 RabbitMQ로 대체

옵션 B: 메모리 큐로 테스트

# test_consumer_local.py
import asyncio
import json
from queue import Queue

# 로컬 메모리 큐
local_queue = Queue()

async def test_event_processing():
    """로컬에서 이벤트 처리 로직만 테스트"""

    # 테스트 이벤트 생성
    test_event = {
        'eventType': 'MINUTES_FINALIZED',
        'data': {
            'meetingId': 'test-001',
            'title': '테스트 회의',
            'minutesId': 'minutes-001',
            'sections': []
        }
    }

    # Consumer의 _process_minutes_event 로직만 테스트
    from src.services.eventhub_consumer import EventHubConsumer

    # 실제 처리 로직 테스트
    # ...

asyncio.run(test_event_processing())

장점:

• ✅ 완전 독립 실행
• ✅ 무료
• ✅ 빠른 테스트

단점:

• ❌ 실제 Event Hub와 다른 환경
• ❌ 통합 테스트 불가

---

권장 솔루션

개발 단계별 권장 방법

단계	권장 방법	이유
로컬 개발	방법 4 (메모리 큐)	빠르고 비용 없음
통합 테스트	방법 2 ($Default 공유)	실제 환경, 단기간
지속적 개발	방법 1 (Tier 업그레이드)	영구 해결, 동시 실행
프로덕션	방법 1 (Standard Tier)	고가용성, 확장성

최종 권장: Tier 업그레이드

이유:

1. ✅ 여러 Consumer Group으로 개발/테스트 분리
2. ✅ 메시지 보존 기간 증가 (1일 → 7일)
3. ✅ 향후 확장 가능 (Capture 등)
4. ✅ 프로덕션 안정성 향상

비용 대비 효과:

• 월 $11 추가로 개발 생산성 향상
• 프로덕션 중단 없이 테스트 가능
• 장기적으로 더 경제적

---

실행 가이드

즉시 테스트가 필요한 경우 (방법 2)

# 1. 프로덕션 Consumer 중지
ps aux | grep "start_consumer.py" | grep -v grep
kill <PID>

# 2. 테스트 실행
cd /Users/daewoong/home/workspace/HGZero/rag
python start_consumer.py

# 3. 테스트 완료 후
# Ctrl+C로 종료

# 4. 프로덕션 재시작
python start_consumer.py &

Tier 업그레이드 후 (방법 1)

# 1. Tier 업그레이드 (Azure Portal 또는 CLI)
az eventhubs namespace update \
  --resource-group rg-digitalgarage-02 \
  --name hgzero-eventhub-ns \
  --sku Standard

# 2. Consumer Group 생성
az eventhubs eventhub consumer-group create \
  --resource-group rg-digitalgarage-02 \
  --namespace-name hgzero-eventhub-ns \
  --eventhub-name hgzero-eventhub-name \
  --name development

# 3. config.yaml 수정
# consumer_group: "development"

# 4. 프로덕션은 계속 실행, 개발 Consumer 별도 실행
python start_consumer.py

---

요약

현재 상황

• ❌ Event Hub Tier: Basic
• ❌ Consumer Group: $Default만 사용 가능
• ❌ 추가 Consumer Group 생성 불가

해결책

1. 단기: 프로덕션 Consumer 잠시 중지하고 테스트 (방법 2)
2. 장기: Standard Tier로 업그레이드 (방법 1) ⭐️

다음 액션

관리자에게 Tier 업그레이드 요청하거나, 긴급하다면 프로덕션 중지 후 테스트 진행

---

참고: Tier 비교

Basic Tier (현재)
├─ Consumer Groups: 1개 ($Default만)
├─ 보존 기간: 1일
├─ 비용: ~$11/월
└─ ❌ 개발/테스트 분리 불가

Standard Tier (권장)
├─ Consumer Groups: 최대 20개 ✅
├─ 보존 기간: 7일
├─ 비용: ~$22/월 (+$11)
└─ ✅ 개발/테스트 완전 분리

Standard Tier로 업그레이드하는 것을 강력히 권장합니다! 🎯