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:**
```bash
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 중지**
```bash
# 기존 Consumer 프로세스 확인
ps aux | grep "start_consumer.py" | grep -v grep

# PID 확인 후 종료
kill <PID>

# 예시
kill 51257
```

**Step 2: 테스트 Consumer 실행**
```bash
cd /Users/daewoong/home/workspace/HGZero/rag
python start_consumer.py
```

**Step 3: 테스트 완료 후 프로덕션 재시작**
```bash
# 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 생성**

```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 실행 스크립트**

```python
# 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: 실행**

```bash
# 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: 메모리 큐로 테스트

```python
# 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)

```bash
# 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)

```bash
# 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로 업그레이드하는 것을 강력히 권장합니다! 🎯