OpenTelemetry Collector 같은 대형 프로젝트를 분석할 때 한 세션에서 전부 처리하려고 하면 문제가 생긴다.

LLM은 컨텍스트 윈도우 안에서 처리하는 정보가 많아질수록 집중도가 떨어지고, 분석 퀄리티도 함께 낮아진다. 소스가 클수록 "전체를 다 보여주는" 방식은 오히려 역효과다.

[X] 한 세션에서 전부 처리
소스 전체 → [단일 에이전트] → 퀄리티 낮은 분석

[O] 멀티에이전트
소스 전체 → 파트 분할 → [스페셜리스트 A] → 검토/검증
                       → [스페셜리스트 B] → 검토/검증  → 최종 합성
                       → [스페셜리스트 C] → 검토/검증

핵심 원칙은 단순하다. 좁은 컨텍스트 = 깊은 분석

접근법: 오케스트레이터 + 스페셜리스트

구조

오케스트레이터 (메인 세션)
  ├── 전체 구조 파악 및 분석 단위 확정
  ├── 서브에이전트들에게 파트 위임
  ├── 결과 검토 및 cross-cutting 검증
  └── 최종 합성
       ↑
스페셜리스트 에이전트들 (병렬 실행)
  ├── Agent A: 핵심 인터페이스 담당
  ├── Agent B: 데이터 수집/전송 담당
  ├── Agent C: 데이터 처리/라우팅 담당
  ├── Agent D: 서비스/확장 담당
  └── Agent E: 설정/인프라 담당

역할 분리

오케스트레이터는 깊이 파지 않는다. 스페셜리스트가 가져온 결과를 검토하고 검증하고 보완 요청하는 게 주 역할이다.

OpenTelemetry Collector에 적용

프로젝트 구조

OpenTelemetry Collector는 멀티모듈 Go 프로젝트로, 컴포넌트 경계가 명확하게 디렉토리로 나뉘어 있어 에이전트 분할에 적합하다.

opentelemetry-collector/
├── component/      # 핵심 인터페이스
├── pdata/          # 텔레메트리 데이터 모델
├── pipeline/       # 파이프라인 시그널 타입
├── consumer/       # 컨슈머 인터페이스
├── receiver/       # 데이터 수집
├── exporter/       # 데이터 전송
├── processor/      # 데이터 처리
├── connector/      # 파이프라인 라우팅
├── extension/      # 확장 기능
├── service/        # 서비스 오케스트레이션
├── otelcol/        # 메인 바이너리
├── confmap/        # 설정 처리
├── featuregate/    # 피처 플래그
└── internal/       # 내부 유틸리티

에이전트 분할 (5개)

구현: Claude Code Agent 툴

Claude Code에서 이 패턴은 별도 인프라 없이 내장 Agent 툴만으로 구현된다.

병렬 실행

# 메인 세션에서 여러 서브에이전트를 한 번에 호출
Agent(subagent_type="Explore", prompt="Core 분석: component, pdata...")
Agent(subagent_type="Explore", prompt="Receiver/Exporter 분석: receiver, exporter...")
Agent(subagent_type="Explore", prompt="Processor/Connector 분석: processor, connector...")
# → 병렬로 실행, 결과가 메인 세션으로 반환

결과 흐름

스페셜리스트 결과 반환
    ↓
오케스트레이터가 검토
    ↓
cross-cutting concerns 교차 검증
    ↓
누락 부분 보완 요청 (필요시 추가 에이전트 실행)
    ↓
최종 합성

프롬프트 설계 원칙

각 스페셜리스트 프롬프트에 반드시 포함해야 할 것:

1. 담당 범위 명시 - 어떤 디렉토리/패키지만 볼 것인지
2. 분석 포인트 - 인터페이스, 의존성, 핵심 로직 중 무엇에 집중할지
3. 결과 형식 - 오케스트레이터가 검토하기 좋은 구조화된 포맷
4. 경계 명시 - 다른 에이전트 담당 영역은 깊이 들어가지 않도록

오케스트레이터 프롬프트에 반드시 포함해야 할 것:

1. cross-cutting 체크리스트 - 각 에이전트 결과 간 연결 포인트
2. 검증 기준 - 누락/모순 여부 판단 기준
3. 보완 요청 조건 - 어떤 경우에 추가 분석을 요청할지

마치며

이 접근법의 핵심은 컨텍스트 관리다. LLM에게 많은 정보를 한꺼번에 주는 것보다, 적절히 쪼개서 각자 깊이 파게 하고 메인이 검증하는 구조가 실제로 더 나은 결과를 만든다.

대형 오픈소스 프로젝트 분석뿐 아니라, 복잡한 버그 디버깅이나 아키텍처 리뷰에도 같은 패턴을 적용할 수 있다.

핵심 개념

Alloy는 컴포넌트를 연결하는 방식으로 동작함.

[소스 컴포넌트] → [처리 컴포넌트] → [목적지 컴포넌트]
     (input)          (process)          (output)

설정 파일(.alloy)에서 컴포넌트를 선언하고 연결하면, Alloy가 그 흐름대로 데이터를 처리함.

역할 1: 수집 (Producer)

앱 서버에 에이전트로 설치되어 로그/메트릭을 읽어서 Kafka 등으로 전송.

파일 로그, stdout, 메트릭
    → Alloy (읽기 + 변환)
        → Kafka

loki.source.file "app" {
  targets    = [{ __path__ = "/var/log/app.log" }]
  forward_to = [otelcol.exporter.kafka.default.input]
}

otelcol.exporter.kafka "default" {
  brokers  = ["kafka:9092"]
  topic    = "logs"
  encoding = "otlp_proto"
}

역할 2: 소비 (Consumer)

Kafka 토픽의 메시지를 읽어서 ClickHouse / Loki 등 백엔드로 적재.

Kafka 토픽
    → Alloy (소비 + 변환)
        → ClickHouse / Loki

otelcol.receiver.kafka "default" {
  brokers  = ["kafka:9092"]
  topic    = "logs"
  encoding = "otlp_proto"

  output {
    logs = [otelcol.exporter.otlphttp.clickhouse.input]
  }
}

지원 입출력

입력 (받을 수 있는 것)

• 파일 로그 (/var/log/...)
• Docker / Kubernetes 컨테이너 로그
• OpenTelemetry (traces, metrics, logs)
• Prometheus metrics
• Kafka 메시지

출력 (보낼 수 있는 것)

• Kafka
• Loki (로그)
• Tempo (트레이스)
• Prometheus / Mimir (메트릭)
• ClickHouse (OTel exporter 경유)
• OpenTelemetry 호환 백엔드 전반

Kafka + ClickHouse 조합에서의 구조

Alloy 없이

앱 서버 ──(직접 produce)──→ Kafka ──→ ClickHouse

• 앱 코드에 Kafka producer 로직 직접 구현 필요
• 포맷 변경 시 앱 코드 수정 필요

Alloy 추가 후

앱 서버
    → Alloy (에이전트, 각 서버에 설치)
        → Kafka
            → Alloy (게이트웨이, 중앙 서버)
                → ClickHouse

앱은 로그만 쓰고, 수집/변환/적재는 Alloy가 담당.

장단점

장점

단점

언제 쓸지 판단 기준

앱 코드를 건드리기 싫다          → Alloy 유용
여러 소스를 통합 수집해야 한다    → Alloy 유용
Kafka 전송 전에 변환이 필요하다   → Alloy 유용

앱이 1~2개이고 포맷이 단순하다    → 앱에서 직접 Kafka producer 써도 충분

Hook 이벤트 종류

설정 위치

~/.claude/settings.json          # 전역 (모든 프로젝트)
.claude/settings.json            # 프로젝트 공유
.claude/settings.local.json      # 프로젝트 로컬 (gitignored)

기본 구조

{
  "hooks": {
    "EventName": [
      {
        "matcher": "regex_pattern",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/script.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hook 타입

Exit Code 동작

Hook Input/Output

Input (stdin으로 전달되는 JSON)

{
  "session_id": "abc123",
  "cwd": "/Users/me/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  },
  "tool_use_id": "toolu_..."
}

Output (exit 0 + stdout JSON)

{
  "continue": true,
  "suppressOutput": false,
  "systemMessage": "optional message to Claude",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "reason"
  }
}

Matcher 패턴

실용 예시

1. 민감 파일 보호

#!/bin/bash
# .claude/hooks/protect-files.sh

FILE=$(cat | jq -r '.tool_input.file_path // empty')

for pattern in ".env" "package-lock.json" ".git/"; do
  if [[ "$FILE" == *"$pattern"* ]]; then
    echo "Blocked: $FILE matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

2. 파일 편집 후 자동 포맷팅

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

3. 권한 자동 승인

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

4. 작업 완료 시 macOS 알림

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

5. Linux 알림

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude needs your attention'"
          }
        ]
      }
    ]
  }
}

6. MCP 도구 호출 로깅

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >> ~/.claude/tool-log.txt"
          }
        ]
      }
    ]
  }
}

HTTP Hook

{
  "type": "http",
  "url": "http://localhost:8080/hooks",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"],
  "timeout": 30
}

유용한 환경 변수

주의사항

• 무한 루프 방지: Stop hook에서 stop_hook_active 값 확인 필요

  if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
    exit 0
  fi

• jq 설치 필요: JSON 파싱에 필수 (brew install jq / apt-get install jq)
• 실행 권한 설정: chmod +x .claude/hooks/my-hook.sh
• Shell 프로필 주의: ~/.zshrc의 unconditional echo는 hook 오작동 유발 가능

관리 명령어

/hooks                  # 설정된 모든 hook 확인 (읽기 전용)

모든 hook 비활성화:

{
  "disableAllHooks": true
}

1. fix_plan.md를 모호하게 적으면 모호하게 만든다

상황: fix_plan.md에 "Django API 연동"이라고만 적었다.

결과: Ralph가 localhost로 하드코딩해버렸다. WSL 환경에서 브라우저로 접근하면 동작하지 않는 코드였지만 지시에 환경 조건이 없었기 때문에 Ralph는 문제로 인식하지 못했다.

교훈: 환경 조건, 접속 방식까지 구체적으로 적어야 한다.

2. 테스트 통과 ≠ 실제 동작

상황: Jest 테스트 11개가 전부 통과했다.

결과: 테스트는 서버 내부에서 supertest로 직접 호출하는 방식이라 localhost가 당연히 동작했다. 실제 브라우저에서 외부 접근하는 케이스는 테스트하지 않았고 Ralph도 그걸 만들라는 지시가 없었으니 만들지 않았다.

교훈: 통합 테스트, E2E 테스트가 필요하면 fix_plan.md에 명시해야 한다.

3. 환경 차이를 알려줘야 한다

상황: WSL 환경에서 Django를 127.0.0.1:8000으로 실행했다.

결과: Windows 브라우저에서 접근이 불가능했다. 0.0.0.0:8000으로 바인딩해야 한다는 걸 Ralph는 몰랐고 CLAUDE.md나 fix_plan.md에도 적혀있지 않았다.

교훈: 실행 환경(OS, 네트워크 구성 등)을 CLAUDE.md에 명시해야 한다.

4. P3를 구체적으로 적지 않으면 껍데기만 나온다

상황: fix_plan.md P3에 "HTML 기본 구조", "API 연동" 수준으로만 적었다.

결과: 화면은 만들어졌지만 실제 동작하는 기능이 없는 껍데기였다.

교훈: "회원가입 → 로그인 → JWT 저장 → Todo CRUD" 처럼 흐름을 구체적으로 적어줬을 때 비로소 제대로 구현됐다.

1. 지시한 것만 한다

fix_plan.md에 적힌 것만 구현한다. 모호하게 적으면 모호하게 만들고, 누락한 건 신경 쓰지 않는다. 결국 품질은 fix_plan.md를 얼마나 잘 쓰느냐에 달려있다.

2. 테스트 범위를 스스로 설계하지 못한다

단위 테스트는 잘 작성하지만, 통합 테스트/E2E 테스트는 명시하지 않으면 안 만든다. 테스트가 통과해도 실제 환경에서 동작하지 않을 수 있다.

3. 환경 차이를 모른다

코드가 실행되는 환경(OS, 네트워크, 인프라)에 대한 맥락이 없다. 개발환경과 운영환경의 차이, 팀마다 다른 인프라 구성은 사람이 알려줘야 한다.

4. 도메인 지식이 없다

비즈니스 규칙, 팀 컨벤션, 히스토리는 CLAUDE.md나 fix_plan.md에 적어줘야 한다. 적지 않으면 일반적인 방식으로 구현한다.

5. 막히면 건너뛴다

연속 3회 같은 에러가 발생하면 해당 항목을 포기하고 넘어간다. 근본 원인을 해결하지 못하는 문제는 사람이 직접 봐야 한다.

6. 코드 리뷰를 스스로 못 한다

테스트와 린트를 통과하면 완료로 판단한다. 보안 취약점, 성능 문제, 유지보수성 같은 건 사람이 리뷰해야 한다.

한마디로

Ralph는 실행력은 뛰어나지만 판단력은 없다.

무엇을 만들지, 어떻게 검증할지, 어떤 환경에서 동작해야 하는지는 사람이 설계해줘야 한다. Ralph는 그 설계를 빠르게 구현하는 도구다.

프로젝트 구조

ralph-test/
├── CLAUDE.md                  # Claude가 자동으로 읽는 프로젝트 설명서
├── PROJECT_STRUCTURE.md       # 구조 설명 문서
├── RALPH_GUIDE.md             # 이 파일 — Ralph 사용 가이드
├── .gitignore
│
├── .claude/
│   └── settings.json          # Claude 권한 + Stop Hook 설정
│
├── .ralph/
│   ├── fix_plan.md            # Ralph 할 일 목록
│   └── PROMPT.md              # Ralph 지시문
│
├── scripts/
│   ├── ralph-loop.sh          # Ralph 실행 스크립트
│   └── ralph-stop-hook.sh     # 완료 조건 검증 Hook
│
├── django-api/
│   ├── .venv/                 # Python 가상환경
│   └── requirements.txt       # Python 패키지 목록
│
└── node-api/
    ├── node_modules/          # Node 패키지
    ├── package.json
    └── eslint.config.js

Ralph를 쓰기 위해 필요한 것

1. CLAUDE.md

"이 프로젝트가 뭔지" Claude에게 알려주는 파일. Claude는 세션 시작 시 이 파일을 자동으로 읽고 프로젝트 컨텍스트를 파악한다.

2. .ralph/fix_plan.md

"뭘 만들어야 하는지" 할 일 목록. Ralph가 이 파일을 보고 순서대로 구현한다.

## P1: 긴급 (반드시 완료)
- [ ] 미완료 항목  ← Claude가 구현
- [x] 완료 항목   ← 구현 + 테스트 통과 후 Claude가 직접 체크

## P2: 중요
- [ ] ...

## P3: 개선
- [ ] ...

3. .ralph/PROMPT.md

"어떻게 일해야 하는지" Claude에게 주는 지시문. 역할, 작업 순서, 완료 조건, 절대 금지 사항을 정의한다.

4. .claude/settings.json

Claude가 실행할 수 있는 명령어(allow)와 없는 명령어(deny), 그리고 Stop Hook 연결을 정의한다.

{
  "permissions": {
    "allow": ["pytest 실행", "git commit", ...],
    "deny": ["rm -rf", "git push force", ...]
  },
  "hooks": {
    "Stop": [{ "command": "bash scripts/ralph-stop-hook.sh" }]
  }
}

5. scripts/ralph-stop-hook.sh

Claude가 멈추려 할 때마다 자동 실행되는 검증 스크립트. 모든 조건을 통과해야만 Claude가 종료할 수 있다.

미완료 항목 있음?     → block (계속 작업하라)
Django 테스트 실패?  → block (고쳐라)
Django 린트 에러?    → block (고쳐라)
Node 테스트 실패?    → block (고쳐라)
Node 린트 에러?      → block (고쳐라)
전부 통과?           → allow  (종료 허용)
max-iterations 초과? → allow  (강제 종료)

6. 환경 세팅

Claude가 실제로 테스트/린트를 실행할 수 있는 환경.

Ralph 실행 방법

# 기본 실행 (최대 30회)
bash scripts/ralph-loop.sh

# 반복 횟수 지정
bash scripts/ralph-loop.sh --max-iterations 10

# 오버나이트 (백그라운드)
nohup bash scripts/ralph-loop.sh --max-iterations 50 > logs/ralph-session.log 2>&1 &

전체 실행 흐름

사람이 fix_plan.md 작성
        ↓
bash scripts/ralph-loop.sh 실행
        ↓
새 브랜치 생성 (ralph/run-YYYYMMDD-HHMM)
        ↓
PROMPT.md → Claude에게 전달
        ↓
┌─── Claude 루프 시작 ──────────────────────┐
│  fix_plan.md 읽기 → 미완료 항목 선택       │
│  테스트 먼저 작성 (TDD — Red)              │
│  구현 (Green)                             │
│  테스트 + 린트 실행                        │
│  통과 → fix_plan.md [x] 표시 + git commit │
│  완료 시도                                 │
│         ↓                                 │
│  ralph-stop-hook.sh 실행                  │
│  ├─ 미통과 → block → 루프 계속 ───────────┘
│  └─ 통과   → allow → 종료
└───────────────────────────────────────────

max-iterations란?

Ralph가 최대 몇 번 반복할지 제한하는 숫자. Claude가 작업 완료를 시도할 때마다 1회로 카운트된다.

결과 확인 방법

# 어디까지 커밋됐는지
git log --oneline

# 항목별 완료 상태 확인
cat .ralph/fix_plan.md

# [x] 완료
# [!] 3회 연속 실패로 건너뜀 → 사람이 직접 확인 필요
# [ ] 미완료 → fix_plan.md 그대로 두고 다시 Ralph 실행

S3 호환 오브젝트 스토리지다. AWS S3와 API가 동일해서 boto3 같은 S3 라이브러리를 그대로 쓸 수 있다. 로컬 또는 온프레미스 환경에서 S3처럼 파일을 저장하고 싶을 때 사용한다.

이 프로젝트에서는 Parquet 파일을 저장하는 스토리지로 사용한다.

Apache Parquet

데이터를 저장하는 파일 형식이다. 컬럼 기반으로 저장하기 때문에 특정 컬럼만 읽는 분석 쿼리에 유리하다. JSON이나 CSV보다 압축률이 높고 읽기 성능이 좋다.

Apache Iceberg

테이블 포맷 스펙이다. 실행되는 서비스가 아니다.

MinIO에 Parquet 파일이 쌓이면 그냥 파일 더미다. 어떤 파일이 어떤 테이블인지, 컬럼이 뭔지, 언제 추가됐는지 알 방법이 없다.

Iceberg는 Parquet 파일들을 테이블처럼 관리할 수 있게 해주는 규칙이다.

Iceberg가 관리하는 파일 구조

system_metrics/
├── data/
│   ├── 00000.parquet
│   └── 00001.parquet
└── metadata/
    ├── snap-001.avro        → 스냅샷 정보
    └── v1.metadata.json     → 테이블 메타데이터

스냅샷 정보

특정 시점에 어떤 Parquet 파일이 테이블에 속했는지 기록한다. 이게 있어서 특정 시점의 데이터를 조회하는 Time Travel이 가능하다.

테이블 메타데이터

컬럼 이름/타입, 파티션 방식, 스키마 변경 이력, 현재 스냅샷 정보를 담고 있다.

Iceberg를 쓰는 이유

Hive Metastore

Iceberg 테이블의 메타데이터 위치를 저장하는 서비스다.

Trino가 쿼리를 실행할 때 다음 순서로 동작한다.

1. Hive Metastore에 "system_metrics 테이블 메타데이터 파일이 어디있어?" 질문
2. Hive Metastore가 MinIO 경로 반환
3. Trino가 그 경로의 메타데이터 파일을 읽어서 어떤 Parquet 파일을 읽어야 하는지 파악
4. MinIO에서 실제 Parquet 파일을 읽어서 쿼리 실행

Hive Metastore 자체의 메타데이터는 DB에 저장된다. 토이 프로젝트에서는 Derby(내장 DB), 프로덕션에서는 PostgreSQL 또는 MySQL을 사용한다.

Trino

분산 SQL 쿼리 엔진이다. Iceberg 포맷을 이해하고 MinIO의 Parquet 파일을 SQL로 조회할 수 있다.

SELECT * FROM iceberg.windows_logs.system_metrics
WHERE timestamp > '2026-03-10'
LIMIT 100;

Trino 자체는 데이터를 저장하지 않는다. MinIO에 있는 파일을 읽어서 쿼리만 실행한다.

전체 흐름 요약

데이터 적재 시

Consumer가 PyIceberg로 Parquet 파일을 MinIO에 저장하고, Iceberg 메타데이터를 업데이트한 뒤 Hive Metastore에 위치를 등록한다.

쿼리 실행 시

Trino가 Hive Metastore에서 메타데이터 위치를 확인하고, MinIO에서 메타데이터와 Parquet 파일을 읽어서 쿼리 결과를 반환한다.

쇼핑몰 데이터 예시

DB (일반 데이터베이스)

쇼핑몰 서비스가 실시간으로 읽고 쓰는 운영 데이터.

users 테이블

orders 테이블

products 테이블

목적: 주문 처리, 재고 확인, 회원 인증 등 서비스 운영에 필요한 CRUD 작업.

데이터 웨어하우스

DB에서 추출한 데이터를 분석 목적에 맞게 변환·적재한 구조. 스타 스키마(Star Schema)를 주로 사용함.

fact_orders 테이블 (사실 테이블)

dim_date 테이블 (날짜 차원 테이블)

분석 쿼리 예시

-- 월별 매출 합계
SELECT
    d.year,
    d.month,
    SUM(f.revenue) AS monthly_revenue
FROM fact_orders f
JOIN dim_date d ON f.date_id = d.date_id
GROUP BY d.year, d.month
ORDER BY d.year, d.month;

-- 상품별 판매량 순위
SELECT
    p.name AS product_name,
    SUM(f.quantity) AS total_quantity
FROM fact_orders f
JOIN dim_product p ON f.product_id = p.product_id
GROUP BY p.name
ORDER BY total_quantity DESC;

목적: 월별 매출 집계, 상품 판매 순위, 유저 구매 패턴 분석 등 BI/리포팅 작업.

데이터 레이크

원시 데이터(로그, 이미지, JSON 등)를 그대로 저장. MinIO 또는 S3 기반.

디렉토리 구조 예시

s3://shopping-datalake/
├── raw/
│   ├── logs/
│   │   ├── 2025/03/01/access.log.gz      # 웹 서버 접근 로그
│   │   └── 2025/03/05/access.log.gz
│   ├── events/
│   │   ├── 2025/03/01/click_events.json  # 클릭 스트림 이벤트
│   │   └── 2025/03/05/click_events.json
│   └── db_snapshot/
│       └── 2025/03/01/orders.parquet     # DB 스냅샷
├── processed/
│   ├── user_behavior/
│   │   └── 2025/03/session_features.parquet
│   └── product_recommendation/
│       └── model_input_2025_03.csv
└── ml_models/
    └── recommendation/
        └── v1.2/model.pkl

활용 예시

목적: 머신러닝 학습, 대규모 로그 분석, 장기 데이터 아카이빙.

전체 데이터 흐름

[쇼핑몰 서비스]
      |
      | 실시간 읽기/쓰기
      v
  [DB (MySQL/PostgreSQL)]
      |
      |-- ETL/CDC --> [데이터 웨어하우스 (Redshift/BigQuery)]
      |                        |
      |                        v
      |                   BI 대시보드 / SQL 분석
      |
      |-- 로그/이벤트 --> [데이터 레이크 (S3/MinIO)]
                                  |
                                  v
                         ML 학습 / 대용량 배치 분석

이 글에서는 ListCreateAPIView가 요청을 받았을 때 내부에서 어떤 경로로 실행되는지 소스 코드를 따라가며 정리한다.

예시 코드

class ScrapeTaskListCreateView(generics.ListCreateAPIView):
    queryset = ScrapeTask.objects.all().order_by('-created_at')
    serializer_class = ScrapeTaskSerializer

이게 전부다. 근데 GET 요청을 보내면 목록이 나오고, POST를 보내면 생성이 된다. 어떻게?

상속 구조

View (Django 기본)
  └── APIView
        └── GenericAPIView
              └── ListModelMixin + CreateModelMixin
                    └── ListCreateAPIView

DRF의 generic view는 여러 클래스를 조합해서 만들어진다.

# rest_framework/generics.py
class ListCreateAPIView(mixins.ListModelMixin,
                        mixins.CreateModelMixin,
                        GenericAPIView):
    def get(self, request, *args, **kwargs):
        return self.list(request, *args, **kwargs)

    def post(self, request, *args, **kwargs):
        return self.create(request, *args, **kwargs)

get()은 self.list()로, post()는 self.create()로 위임한다. list()와 create()는 각각 ListModelMixin, CreateModelMixin에 정의되어 있다.

요청 흐름 추적

1. urls.py에서 .as_view() 호출

path("tasks/", ScrapeTaskListCreateView.as_view())

as_view()는 View(Django 기본)에 정의된 클래스 메서드다. 호출하면 클래스를 함수처럼 쓸 수 있는 view 함수를 반환한다. Django 라우터는 함수만 받기 때문에 이 변환이 필요하다.

2. 요청이 들어오면 dispatch() 실행

HTTP 요청이 들어오면 APIView.dispatch()가 호출된다.

# rest_framework/views.py
def dispatch(self, request, *args, **kwargs):
    request = self.initialize_request(request, *args, **kwargs)
    self.initial(request, *args, **kwargs)  # 인증, 권한, 쓰로틀 체크

    if request.method.lower() in self.http_method_names:
        handler = getattr(self, request.method.lower(), self.http_method_not_allowed)

    response = handler(request, *args, **kwargs)
    return self.finalize_response(request, response, *args, **kwargs)

request.method.lower()로 HTTP 메서드를 소문자로 변환한 뒤, 같은 이름의 메서드를 자기 자신에서 찾는다. GET이면 self.get, POST면 self.post.

3. get() → list() 실행

# rest_framework/mixins.py
class ListModelMixin:
    def list(self, request, *args, **kwargs):
        queryset = self.filter_queryset(self.get_queryset())
        serializer = self.get_serializer(queryset, many=True)
        return Response(serializer.data)

get_queryset()은 클래스에 선언한 queryset을 반환한다. get_serializer()는 serializer_class로 시리얼라이저 인스턴스를 만든다. serializer.data는 Python 딕셔너리로 변환된 데이터고, Response가 이걸 JSON으로 렌더링한다.

4. post() → create() 실행

# rest_framework/mixins.py
class CreateModelMixin:
    def create(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        self.perform_create(serializer)
        return Response(serializer.data, status=status.HTTP_201_CREATED)

    def perform_create(self, serializer):
        serializer.save()

request.data로 요청 바디를 받아서 유효성 검사 후 저장한다. perform_create()를 별도로 분리한 이유는 오버라이드하기 쉽게 하기 위해서다. 예를 들어 저장 후 Celery 태스크를 발행하고 싶다면:

def perform_create(self, serializer):
    task = serializer.save()
    scrape_url.delay(task.id)

get_serializer_class()는 언제 쓰나

serializer_class를 하나만 선언하면 GET/POST 모두 같은 시리얼라이저를 사용한다. GET 응답에는 전체 필드를 주고, POST 요청에는 일부 필드만 받고 싶다면 get_serializer_class()를 오버라이드한다.

class ScrapeTaskListCreateView(generics.ListCreateAPIView):
    queryset = ScrapeTask.objects.all()

    def get_serializer_class(self):
        if self.request.method == "POST":
            return ScrapeTaskCreateSerializer
        return ScrapeTaskSerializer

get_serializer()가 내부에서 get_serializer_class()를 호출하기 때문에, 메서드에 따라 다른 시리얼라이저가 선택된다.

함수형 뷰와 비교

같은 기능을 함수형 뷰로 작성하면 흐름이 훨씬 명확하다.

@api_view(["GET", "POST"])
def task_list(request):
    if request.method == "GET":
        tasks = ScrapeTask.objects.all().order_by("-created_at")
        serializer = ScrapeTaskSerializer(tasks, many=True)
        return Response(serializer.data)

    elif request.method == "POST":
        serializer = ScrapeTaskCreateSerializer(data=request.data)
        if serializer.is_valid():
            task = serializer.save()
            scrape_url.delay(task.id)
            return Response(ScrapeTaskSerializer(task).data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

Generic View는 이 코드를 추상화한 것이다. 코드량은 줄지만 내부 동작을 모르면 커스터마이즈할 때 막힌다.

정리

Generic View를 쓸 때 뭔가 안 되면 dispatch → get/post → list/create 순으로 소스 코드를 따라가면 대부분 원인을 찾을 수 있다.

Claude에서 MCP 서버를 구축하고 PostgreSQL 데이터베이스를 연동하는 실전 가이드

MCP란 무엇인가

MCP(Model Context Protocol) 는 Anthropic에서 개발한 표준 프로토콜로, Claude와 외부 데이터 소스를 연결하는 인터페이스임.

핵심 개념

MCP는 Claude가 외부 시스템과 통신할 수 있도록 하는 브릿지 역할을 함. 데이터베이스, API, 파일 시스템 등 다양한 데이터 소스에 접근 가능함.

┌─────────────┐         ┌─────────────┐         ┌──────────────┐
│             │         │             │         │              │
│   Claude    │ ◄─────► │ MCP Server  │ ◄─────► │  PostgreSQL  │
│             │         │             │         │              │
└─────────────┘         └─────────────┘         └──────────────┘
    자연어 질의          프로토콜 변환            SQL 실행

MCP의 장점

환경 구축하기

필수 요구사항

MCP 서버 구축을 위해 다음 도구가 필요함:

• Node.js: MCP 서버 실행 환경
• Claude Code CLI: Claude 명령줄 도구
• PostgreSQL: 연동할 데이터베이스 인스턴스

Node.js 설치 확인

node --version
npm --version

PostgreSQL 설치 확인

psql --version

MCP 서버 설정

1. 설정 파일 위치

Claude의 MCP 설정 파일은 다음 위치에 있음:

~/.claude/config.json

2. PostgreSQL MCP 서버 추가

설정 파일을 열고 다음 내용을 추가함:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    }
  }
}

설정 항목 설명:

• "postgres": MCP 서버의 이름 (임의로 지정 가능)
• "command": 실행할 명령어 (npx는 npm 패키지를 즉시 실행)
• "args": 명령어 인자
  • -y: 자동으로 yes 응답
  • @modelcontextprotocol/server-postgres: PostgreSQL MCP 서버 패키지
  • postgresql://localhost/mydb: PostgreSQL 연결 URL

3. 연결 문자열 설정

PostgreSQL 연결 문자열 형식:

postgresql://[username[:password]@][host][:port][/database]

로컬 개발 환경:

"args": [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://localhost/mydb"
]

사용자 인증:

"args": [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://user:password@localhost/mydb"
]

원격 서버:

"args": [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://user:password@remote-host:5432/mydb"
]

SSL 연결:

"args": [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://user:password@remote-host:5432/mydb?sslmode=require"
]

4. 여러 MCP 서버 설정

여러 데이터베이스를 동시에 연결할 수 있음:

{
  "mcpServers": {
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:pass@prod-server:5432/production"
      ]
    },
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/development"
      ]
    },
    "postgres-test": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/test"
      ]
    }
  }
}

MCP 서버 시작 및 확인

1. Claude 재시작

설정 파일을 수정한 후 Claude를 재시작해야 함:

# Claude 프로세스 종료 후 다시 시작
claude

2. MCP 서버 연결 확인

Claude를 시작하면 MCP 서버가 자동으로 실행됨. 연결 상태 확인:

사용 가능한 도구 확인:

Available MCP Tools:
- mcp__postgres__query: Execute read-only SQL queries

3. 연결 테스트

간단한 쿼리로 연결을 테스트함:

자연어로 질의:

"테이블 목록 보여줘"

또는 직접 SQL 요청:

"SELECT * FROM pg_tables WHERE schemaname = 'public' 실행해줘"

정상적으로 테이블 목록이 출력되면 연결 성공임.

실전 사용 예제

기본 데이터베이스 조회

MCP 서버가 연결되면 자연어로 데이터베이스 조회 가능:

예제 1: 테이블 목록

사용자: "데이터베이스에 어떤 테이블이 있어?"
Claude: [자동으로 적절한 쿼리 실행 후 결과 제공]

예제 2: 테이블 구조 확인

사용자: "users 테이블 구조 알려줘"
Claude: [테이블 스키마 정보 제공]

예제 3: 데이터 조회

사용자: "users 테이블에서 최근 가입한 사용자 10명 보여줘"
Claude: [데이터 조회 및 분석 결과 제공]

자동 쿼리 생성

Claude가 자연어를 SQL로 자동 변환:

사용자: "이번 달 주문 건수가 몇 개야?"
Claude: → SELECT COUNT(*) FROM orders
          WHERE created_at >= DATE_TRUNC('month', CURRENT_DATE)

사용자: "가장 많이 팔린 상품 5개 알려줘"
Claude: → SELECT product_name, COUNT(*) as sales
          FROM orders
          GROUP BY product_name
          ORDER BY sales DESC
          LIMIT 5

고급 설정

환경 변수 활용

민감한 정보는 환경 변수로 관리하는 것이 좋음:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DATABASE_URL}"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost/mydb"
      }
    }
  }
}

또는 시스템 환경 변수 사용:

# .bashrc 또는 .zshrc
export DATABASE_URL="postgresql://user:password@localhost/mydb"

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DATABASE_URL}"
      ]
    }
  }
}

타임아웃 설정

장시간 실행되는 쿼리를 위해 타임아웃을 설정할 수 있음:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ],
      "timeout": 30000
    }
  }
}

연결 풀 설정

PostgreSQL 연결 풀링 옵션:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb?max_pool_size=10&min_pool_size=2"
      ]
    }
  }
}

트러블슈팅

MCP 서버가 시작되지 않는 경우

증상: Claude 시작 시 MCP 서버 연결 실패

해결 방법:

1. Node.js 설치 확인

   node --version
   npm --version

2. 설정 파일 확인

   cat ~/.claude/config.json

3. JSON 문법 오류 확인

• 콤마 누락 확인
• 괄호 짝 맞는지 확인
• 따옴표 올바른지 확인

4. PostgreSQL 연결 확인

   psql -h localhost -U user -d mydb

인증 오류

증상: password authentication failed 에러

해결 방법:

1. 사용자 계정 확인

   SELECT usename FROM pg_user;

2. 비밀번호 확인

   psql -h localhost -U user -d mydb

3. pg_hba.conf 설정 확인

   # PostgreSQL 설정 파일 위치 확인
   psql -c "SHOW hba_file"

연결 거부 오류

증상: Connection refused 에러

해결 방법:

1. PostgreSQL 실행 확인

   pg_isready
   # 또는
   sudo systemctl status postgresql

2. 포트 확인

   netstat -an | grep 5432

3. 방화벽 설정 확인

   sudo ufw status

쿼리 권한 오류

증상: permission denied 에러

해결 방법:

MCP 서버는 읽기 전용이므로 SELECT 권한만 필요:

GRANT SELECT ON ALL TABLES IN SCHEMA public TO user;

보안 고려사항

읽기 전용 접근

MCP 서버는 기본적으로 읽기 전용 쿼리만 지원:

전용 사용자 생성

MCP 전용 읽기 전용 사용자 생성 권장:

-- 읽기 전용 사용자 생성
CREATE USER mcp_readonly WITH PASSWORD 'secure_password';

-- SELECT 권한 부여
GRANT CONNECT ON DATABASE mydb TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;

-- 향후 생성될 테이블에도 자동 권한 부여
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO mcp_readonly;

연결 정보 보호

민감한 연결 정보는 환경 변수나 별도 파일로 관리:

# .env 파일 생성
DATABASE_URL=postgresql://mcp_readonly:password@localhost/mydb

# 권한 설정
chmod 600 .env

SSL/TLS 암호화

프로덕션 환경에서는 SSL 연결 필수:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:pass@host:5432/db?sslmode=require"
      ]
    }
  }
}

SSL 모드 옵션:

• disable: SSL 사용 안 함
• require: SSL 필수
• verify-ca: CA 인증서 검증
• verify-full: 호스트명까지 검증

실전 활용 사례

1. 데이터 탐색

자연어로 데이터베이스 구조와 내용 탐색:

"어떤 테이블이 있어?"
"users 테이블 구조 알려줘"
"users 테이블 레코드 몇 개야?"
"최근 생성된 데이터 10개 보여줘"

2. 비즈니스 분석

비즈니스 질문을 바로 데이터로 확인:

"이번 달 신규 가입자 수는?"
"어제 매출은 얼마야?"
"가장 인기 있는 카테고리는?"
"지역별 주문 분포 보여줘"

3. 데이터 검증

데이터 품질 확인:

"NULL 값이 있는 레코드 있어?"
"중복된 이메일 있어?"
"유효하지 않은 날짜 데이터 있어?"

4. 트러블슈팅

문제 발생 시 빠른 확인:

"최근 1시간 에러 로그 보여줘"
"실패한 트랜잭션 조회해줘"
"응답 시간이 긴 API 요청 찾아줘"

MCP vs 기존 방식 비교

기존 방식

# 터미널에서 psql 접속
psql -h localhost -U user -d mydb

# SQL 작성
mydb=# SELECT COUNT(*) FROM users WHERE created_at > NOW() - INTERVAL '7 days';

# 결과 확인
 count
-------
   143

MCP 방식

사용자: "지난 7일간 가입한 사용자 수 알려줘"
Claude: 지난 7일간 143명의 사용자가 가입했습니다.

장점:

• SQL 문법 몰라도 됨
• 자연어로 질의
• 결과 자동 해석
• 연속 질문 가능

마치며

MCP를 활용하면 Claude가 PostgreSQL 데이터베이스에 직접 접근하여 자연어로 데이터를 조회할 수 있음.

구축 요약:

1. ~/.claude/config.json 파일 생성
2. PostgreSQL MCP 서버 설정 추가
3. 연결 문자열 입력
4. Claude 재시작
5. 자연어로 데이터 조회

핵심 장점:

• 쉬운 설정: 설정 파일 하나로 연동 완료
• 자연어 지원: SQL 없이 데이터 조회
• 안전한 접근: 읽기 전용으로 데이터 보호
• 빠른 분석: 대화형으로 즉시 데이터 확인

MCP 서버 구축은 간단하지만, 데이터 분석 워크플로우를 혁신적으로 개선할 수 있음.

참고 자료

공식 문서:

• MCP 공식 문서
• Claude Code CLI
• PostgreSQL 문서

MCP 서버:

• MCP Server 저장소
• PostgreSQL MCP Server

웹 폼에서 봇을 막기 위해 CAPTCHA를 많이 씀. Django에서 사용할 수 있는 대표적인 CAPTCHA 3가지를 직접 테스트해봄.

1. Google reCAPTCHA v2

Google에서 제공하는 가장 널리 사용되는 CAPTCHA 서비스임. "I'm not a robot" 체크박스 방식으로, 행동 분석 기반으로 봇을 탐지함. 의심스러운 경우 이미지 선택 챌린지가 나옴.

가장 높은 인지도와 풍부한 레퍼런스, 안정적인 서비스가 장점임. 다만 Google에 데이터가 전송되기 때문에 프라이버시 이슈가 있음.

  from django_recaptcha.fields import ReCaptchaField
  from django_recaptcha.widgets import ReCaptchaV2Checkbox

  class MyForm(forms.Form):
      captcha = ReCaptchaField(widget=ReCaptchaV2Checkbox())

2. hCaptcha

reCAPTCHA의 프라이버시 친화적 대안으로 떠오른 서비스임. GDPR 준수가 잘 되어 있고, Cloudflare가 한때 이걸 기본 CAPTCHA 로 채택했었음. 무료 티어가 제공됨.

프라이버시 보호와 GDPR 친화적인 점이 장점임. 다만 reCAPTCHA보다 인지도가 낮고, 간혹 챌린지가 어려울 때가 있음.

  from hcaptcha.fields import hCaptchaField

  class MyForm(forms.Form):
      captcha = hCaptchaField()

3. Cloudflare Turnstile

Cloudflare에서 2022년에 출시한 최신 CAPTCHA임. 대부분의 경우 사용자 상호작용이 필요 없고, 완전 무료로 제공됨. 프라이버시 보호도 잘 되어 있음.

사용자 경험이 가장 좋고 완전 무료인 게 장점임. 다만 상대적으로 신생 서비스라 레퍼런스가 적음.

  from turnstile.fields import TurnstileField

  class MyForm(forms.Form):
      captcha = TurnstileField()

테스트 키 정보

개발 환경에서 테스트할 때 각 서비스에서 제공하는 테스트 키를 사용하면 됨. 테스트 키는 항상 검증을 통과함.

총평

Django에서 세션 저장소로 Redis Cluster를 사용하려고 django-redis를 설정했는데 아래 에러가 발생함.

ClusterError: Command # 1 (EXISTS ...) of pipeline caused error: TTL exhausted.

분명히 Redis Cluster 구성도 잘 됐고, redis-py로 직접 테스트하면 잘 됨. 근데 Django에서만 안 됨.

원인 분석

Redis Cluster의 데이터 분산 구조

Redis Cluster는 16384개의 해시 슬롯으로 데이터를 분산 저장함.

키 → CRC16(키) % 16384 → 슬롯 번호 → 담당 노드

┌─────────────────┬─────────────┬─────────────┐ │ Master 1 │ Master 2 │ Master 3 │ │ 슬롯 0-5460 │ 슬롯 5461- │ 슬롯 10923- │ │ │ 10922 │ 16383 │ ├─────────────────┼─────────────┼─────────────┤ │ "user:1" │ "user:2" │ "session:a" │ │ → 슬롯 1234 │ → 슬롯 7890│ → 슬롯 │ │ │ │ 12345 │ └─────────────────┴─────────────┴─────────────┘

키의 해시값에 따라 서로 다른 노드에 저장됨.

Pipeline이란?

일반적인 Redis 요청은 요청 → 응답 → 요청 → 응답 순서로 동작함.

일반 방식 (느림): Client Redis │── GET a ──────▶│ │◀───── "1" ─────│ │── GET b ──────▶│ │◀───── "2" ─────│

네트워크 왕복: 2번

Pipeline은 여러 명령을 한 번에 보내고 응답도 한 번에 받음. 네트워크 왕복을 줄여서 성능이 좋음.

Pipeline 방식 (빠름): Client Redis │── GET a ──────▶│ │── GET b ──────▶│ │◀───── "1" ─────│ │◀───── "2" ─────│

네트워크 왕복: 1번

Redis Cluster + Pipeline = 문제

단일 Redis에서는 모든 키가 같은 서버에 있으니까 pipeline 문제 없음.

근데 Redis Cluster에서는 키마다 담당 노드가 다름.

Client가 Master 1에 Pipeline 전송:

│── EXISTS session:xyz ──▶│ Master 1
│── GET session:xyz ─────▶│

문제:

• session:xyz → 슬롯 12345 → Master 3 담당인데?

• Master 1한테 물어봤으니까 → MOVED 응답 반환

  Master 1 입장에서는 "나한테 왜 물어봄? Master 3 가서 물어봐"라고 응답하는 것임.

  MOVED 12345 172.28.0.23:7003

  클라이언트가 이걸 받고 Master 3으로 재시도 → 또 문제 발생 → 반복 → TTL exhausted

django-redis가 문제인 이유

django-redis의 DefaultClient는 내부적으로 pipeline을 사용함.

django-redis 내부 코드 (간략화)

  def get(self, key):
      with self.client.pipeline() as pipe:
          pipe.exists(key)   # ← 이 키가 다른 노드에 있으면 MOVED
          pipe.get(key)      # ← 마찬가지
          return pipe.execute()  # ← 여기서 TTL exhausted 터짐

  django-redis는 원래 단일 Redis용으로 만들어진 거라서 Cluster 환경을 고려 안 함.

해결 방법

커스텀 Connection Factory 작성

  # redis-py의 RedisCluster를 직접 사용하는 Connection Factory를 만들어서 주입함.

  app/config/redis_cluster_factory.py

  from django_redis.pool import ConnectionFactory
  from redis.cluster import RedisCluster, ClusterNode

  class RedisClusterConnectionFactory(ConnectionFactory):
      def __init__(self, options):
          self._pool = None
          self._client = None
          self._options = options

      def connect(self, url):
          if self._client is None:
              startup_nodes = [
                  ClusterNode('172.28.0.21', 7001),
                  ClusterNode('172.28.0.22', 7002),
                  ClusterNode('172.28.0.23', 7003),
              ]
              self._client = RedisCluster(
                  startup_nodes=startup_nodes,
                  decode_responses=False,
                  skip_full_coverage_check=True,
              )
          return self._client

      def disconnect(self, connection):
          if self._client:
              self._client.close()
              self._client = None

      def get_connection(self, params):
          return self.connect(None)

  # settings.py

  SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
  SESSION_CACHE_ALIAS = 'default'

  CACHES = {
      'default': {
          'BACKEND': 'django_redis.cache.RedisCache',
          'LOCATION': 'redis://172.28.0.21:7001/0',
          'OPTIONS': {
              'CLIENT_CLASS': 'django_redis.client.DefaultClient',
              'CONNECTION_FACTORY': 'config.redis_cluster_factory.RedisClusterConnectionFactory',
          },
      }
  }

왜 이게 해결이 되는가?

  RedisCluster 객체는 내부적으로 키의 슬롯을 계산해서 올바른 노드에 직접 요청함.

  rc = RedisCluster(...)

  rc.get("user:1")    # → 슬롯 계산 → Master 1로 요청
  rc.get("user:2")    # → 슬롯 계산 → Master 2로 요청
  rc.get("session:a") # → 슬롯 계산 → Master 3로 요청

  MOVED 응답이 와도 자동으로 올바른 노드로 리다이렉트 처리함.

요약

참고

Docker 환경에서 Redis Cluster 구성 시 고정 IP + cluster-announce-ip 설정도 필수임. 안 하면 클라이언트가 노드 IP에 접근 못해서 똑같이 TTL exhausted 에러 남.

docker-compose.yml

redis-node1: command: > redis-server --cluster-announce-ip 172.28.0.21 --cluster-announce-port 7001 networks: app-network: ipv4_address: 172.28.0.21

각 방식별 Failover 메커니즘을 상세히 정리함.

1. Standalone (Replication Only)

가장 기초적인 Master-Replica 구조임. 자동 복구가 불가능하다는 것이 핵심.

장애 복구 프로세스 (수동)

1. 장애 발생: Master 노드 다운.
2. 서비스 중단: Application에서 쓰기(Write) 작업 실패 발생.
3. 관리자 개입:
   • 개발자/엔지니어가 알람을 보고 접속.
   • Replica 노드에 직접 접속하여 승격 명령어 실행.

     # Replica 노드에서 실행하여 Master로 승격
     REPLICAOF NO ONE

4. 설정 변경: Application 서버의 Redis 연결 설정을 새로운 Master IP로 변경 후 배포/재시작.

특징

• Down Time이 긺: 사람이 직접 대응해야 하므로 야간이나 휴일 장애 시 서비스 중단 시간이 매우 길어질 수 있음.
• 감시 주체 없음: 별도의 헬스 체크 시스템이 없으면 장애 인지가 늦음.

2. Redis Sentinel (센티널)

별도의 감시 프로세스(Sentinel)가 관리자를 대신해 장애를 감지하고 복구함.

장애 복구 프로세스 (자동)

1. 장애 감지 (SDOWN -> ODOWN):
   • Sentinel 인스턴스가 Master에게 주기적으로 PING을 날림.
   • 응답이 없으면 해당 Sentinel은 SDOWN(Subjective Down, 주관적 다운)으로 인지.
   • 설정된 Quorum(정족수) 이상의 Sentinel들이 "얘 죽은 거 맞다"고 동의하면 ODOWN(Objective Down, 객관적 다운)으로 확정.
2. 리더 선출: Sentinel들끼리 투표하여 Failover를 진행할 '리더 Sentinel'을 선출함.
3. Failover 실행:
   • 리더 Sentinel이 건강한 Replica 중 하나를 선택.
   • 해당 Replica에게 REPLICAOF NO ONE 명령어를 전송해 Master로 승격시킴.
   • 나머지 Replica들이 새 Master를 바라보도록 설정 변경 (REPLICAOF new-master-ip port).
4. Client 전파:
   • Client는 Sentinel에게 현재 Master 주소를 질의하다가 변경된 주소를 받게 됨 (Pub/Sub 메커니즘 활용).

특징

• 감시 주체: 별도의 redis-sentinel 프로세스.
• 클라이언트 지원 필수: Application 코드(라이브러리)가 Sentinel 기능을 지원해야 함. (직접 Redis IP를 박는 게 아니라 Sentinel IP 리스트를 설정함).

3. Redis Cluster (클러스터)

Sentinel 없이 노드들끼리 서로 감시(P2P)하며 집단지성으로 복구함.

장애 복구 프로세스 (자동 - Gossip Protocol)

1. 상호 감시: 클러스터 내 모든 Master 노드는 서로 mesh 구조로 연결되어 PING/PONG을 주고받음 (Gossip Protocol).
2. 장애 감지 (PFAIL -> FAIL):
   • Node A가 Node B에게 응답을 못 받으면 PFAIL(Possible Fail)로 마킹.
   • 다른 Master 노드들에게도 Gossip 메시지로 Node B 상태를 물어봄.
   • 과반수 이상의 Master가 PFAIL이라 판단하면 FAIL 상태로 확정하고 클러스터 전체에 브로드캐스팅.
3. 승격 투표:
   • 죽은 Master의 Replica가 이를 감지하고 승격 선거를 시작. ("나 Master 할게 투표 좀 해줘")
   • 살아있는 다른 Master 노드들이 투표(Vote)함.
4. Failover 실행:
   • 과반수 표를 얻은 Replica가 Master로 승격.
   • 자신이 담당할 Hash Slot 정보를 갱신하고 클러스터 설정(Epoch)을 업데이트.

특징

• 감시 주체: Redis Master 노드 자신들 (Sentinel 불필요).
• 리다이렉션: 클라이언트는 아무 노드나 접속했다가, 해당 Key가 다른 노드에 있으면 MOVED 에러와 함께 올바른 주소로 리다이렉트됨.

4. 요약 비교

결론

• Sentinel: 별도의 감시반(보디가드)을 고용해서 지키게 하는 방식.
• Cluster: 구성원들끼리 서로 생존 신고하며 빈자리를 채우는 자치적인 방식.

각 방식의 특징과 장단점을 정리함.

1. Standalone (Replication) : 기본 복제 구성

가장 기본적인 형태. Master 노드 1개와 Replica(Slave) 노드 1개 이상으로 구성됨.

동작 원리

• Master: 데이터 쓰기(Write)와 읽기(Read) 모두 수행.
• Replica: Master 데이터를 비동기(Asynchronous)로 복제해 유지. 주로 읽기 전용(Read-Only)으로 설정해 Read 트래픽 분산 용도로 사용.

장점

• 구성이 가장 간단함.
• Replica를 늘려 Read 성능 확보 가능.

단점

• SPOF (Single Point of Failure): Master 장애 시 쓰기 불가.
• 수동 복구: 장애 시 관리자가 직접 Replica를 Master로 승격시켜야 함.
• Scale-up 의존: 데이터 증가 시 장비 스펙 업(Scale-up) 외엔 방법 없음.

2. Redis Sentinel : 고가용성(HA) 확보

Replication의 '수동 복구' 한계를 해결하기 위한 구조. 별도의 Sentinel(감시자) 프로세스가 Redis를 모니터링함.

동작 원리

1. Monitoring: Sentinel이 Master, Replica 상태 주기적 감시.
2. Notification: 장애 감지 시 관리자에게 알림 발송.
3. Automatic Failover: Master 다운 시, Sentinel 투표로 Replica 중 하나를 Master로 승격.
4. Configuration Provider: 클라이언트는 Sentinel에 접속해 현재 Master 주소를 받아옴.

특징

• 홀수 구성: 과반수 투표(Quorum) 위해 Sentinel은 최소 3개 이상 홀수로 구성 필요.
• 데이터 샤딩 불가: 모든 데이터가 하나의 Master에 저장되므로 대용량 처리에 한계 존재.

3. Redis Cluster : 샤딩 + 고가용성

단일 서버 메모리 초과나 쓰기 트래픽 분산이 필요할 때 쓰는 수평 확장(Scale-out) 구조.

동작 원리 (Hash Slot)

• Sharding: 전체 데이터를 16,384개 Hash Slot으로 분할.
• 분산 저장: Key를 CRC16 해시 함수로 돌려 저장할 슬롯(노드) 결정.

  SLOT = CRC16(key) mod 16384

• Failover: Master별로 Replica를 가지며, 장애 시 해당 Replica가 자동 승격 (Sentinel 없이 자체 수행).

장점

• 무한한 확장성: 노드 추가로 용량과 처리량 증대 가능.
• HA: 일부 노드 장애에도 전체 서비스 중단 없음.

단점

• 설정과 관리가 복잡함.
• Multi-key 연산 제한: 서로 다른 노드에 있는 Key 간 트랜잭션이나 MGET 사용이 어려움.

4. 비교

5. 결론: 선택 가이드

• 소규모 / 단순 캐시: Standalone (Replication)으로 충분함.
• 다운타임 치명적 / 데이터 적음: Sentinel 도입해 자동 장애 복구 체계 구축.
• 대규모 데이터 / 쓰기 트래픽 많음: Cluster로 데이터 분산 처리 필요.

Docker Compose 기반 3-Node CrateDB 클러스터 구축 시 필수적인 핵심 개념(Node, Shard, Replica)과 장애 발생 시 자동 복구(Failover) 프로세스 정리.

1. 핵심 아키텍처 정의

🔹 노드 (Node)

• 정의: 클러스터를 구성하는 하나의 서버 인스턴스(컨테이너).
• 역할: 데이터 저장, 클라이언트 요청 처리 및 노드 간 통신을 통한 클러스터 형성.
• 구성: 현재 3개의 컨테이너(node1, node2, node3)가 하나의 논리적 클러스터(crate-cluster)로 결합.

🔹 샤드 (Shard)

• 정의: 대용량 데이터의 분산 저장을 위해 테이블을 논리적으로 분할한 단위.
• 목적: 데이터 수평적 확장(Scale-out) 및 병렬 처리 지원.
• 설정: 별도 설정 부재 시 테이블당 기본 4개의 샤드로 분할 및 노드 간 균등 배포.

🔹 레플리카 (Replica)

• 정의: 데이터 유실 방지를 위한 원본 샤드(Primary Shard)의 복제본.
• 규칙: 가용성 보장을 위해 반드시 원본 샤드와 서로 다른 노드에 배치.
• 설정: 3-Node 구성 시 replicas=1 (원본 1 + 사본 1) 자동 적용.

2. 데이터 저장 프로세스 (Normal State)

데이터 쓰기(INSERT) 요청 시의 내부 처리 흐름.

1. 라우팅 (Routing): 데이터 ID의 해시(Hash) 연산을 통해 저장될 샤드 위치 결정.
2. 동기 복제 (Synchronous Replication):
   • Primary Shard(원본) 기록: 라우팅된 노드의 원본 샤드에 데이터 기록.
   • Replica Shard(복제본) 전파: 즉시 다른 노드의 복제본 샤드로 데이터 전송 및 기록 요청.
   • 응답(Ack): 원본과 복제본 모두 저장 완료 확인 후 클라이언트에 성공 응답 반환.
3. 특징: 강력한 데이터 정합성(Consistency) 보장 및 단일 노드 장애 시 데이터 유실 방지.

3. 장애 대응 및 자동 복구 (Failover Scenario)

시나리오: 정상 운영(Green) 중 Node 3 다운 발생 시 클러스터의 대응 메커니즘.

단계 1: 장애 감지 및 승격 (Failover)

Node 3에 위치하던 Primary Shard 소실 발생.

• 승격 (Promotion): 잔존 노드(Node 1 또는 2)에 위치한 Replica Shard를 즉시 Primary Shard로 승격.
• 가용성 유지: 새로운 Primary를 통해 읽기/쓰기 서비스 지속.
• 상태 변경: 클러스터 상태 Green ➜ Yellow 전환 (서비스 정상, 복제본 부족 상태).

단계 2: 재복제 (Re-replication / Self-Healing)

승격 후 replicas=1 정책 미달(Replica 부재) 상태 해소 과정.

• 복제 수행: 잔존 노드 중 데이터가 없는 노드에 새로운 Replica Shard 생성 및 데이터 복사.
• 복구 완료: 원본 1 + 사본 1 구조 재확립.
• 상태 변경: 클러스터 상태 Yellow ➜ Green 복귀.

4. 노드 복구와 동기화 (Node Recovery)

다운되었던 Node 3 재기동 및 클러스터 재합류 시 동작.

Peer Recovery (델타 동기화)

전체 데이터 복사가 아닌 효율적인 복구 수행.

1. 비교 (Check): Node 3의 데이터 상태와 현재 Primary Shard의 상태 비교.
2. 동기화 (Sync): 다운타임 동안 발생한 변경분(Delta) 트랜잭션만 전송 및 반영.
3. 리밸런싱 (Rebalancing): 데이터 균형을 위해 특정 노드에 편중된 샤드를 Node 3로 재배치.

5. 요약: 추상화와 투명성

애플리케이션(Client) 관점에서의 이점.

• 투명성 (Transparency): 샤딩, 복제, 승격 등 내부 복잡성은 DBMS 엔진이 전담. 개발자는 물리적 노드 상태와 무관하게 논리적 엔드포인트 사용.
• 코디네이터 노드 (Coordinator Node): 클라이언트 요청을 수신한 노드가 최신 클러스터 메타데이터를 기반으로 정확한 데이터 위치(Primary Shard)로 쿼리 라우팅 수행.
• 결론: 인프라 장애 발생 시에도 지속적인 서비스 제공(High Availability) 및 데이터 무결성 보장.

Docker Compose를 사용하여 3-Node CrateDB 클러스터를 구축할 때, 가장 중요한 것은 command 섹션의 설정값.

CrateDB는 Elasticsearch를 기반으로 하기 때문에 설정 방식이 유사하며 스플릿 브레인(Split-Brain) 방지와 데이터 무결성(Data Integrity)을 위해 아래 옵션들을 정확히 이해하고 설정해야함.

docker-compose.yml 설정 예시

  # CrateDB Node 1 (Seed / Master)
  crate-node1:
    image: crate:latest
    container_name: crate-node1
    ports:
      - "4200:4200"
      - "5432:5432"
    command: >
      crate
      -Cnetwork.host=_site_
      -Ccluster.name=crate-cluster
      -Cnode.name=crate-node1
      -Cdiscovery.seed_hosts=crate-node2,crate-node3
      -Ccluster.initial_master_nodes=crate-node1,crate-node2,crate-node3
      -Cgateway.expected_data_nodes=3
      -Cgateway.recover_after_data_nodes=2
    restart: always

  # CrateDB Node 2
  crate-node2:
    image: crate:latest
    container_name: crate-node2
    command: >
      crate
      -Cnetwork.host=_site_
      -Ccluster.name=crate-cluster
      -Cnode.name=crate-node2
      -Cdiscovery.seed_hosts=crate-node1,crate-node3
      -Ccluster.initial_master_nodes=crate-node1,crate-node2,crate-node3
      -Cgateway.expected_data_nodes=3
      -Cgateway.recover_after_data_nodes=2
    restart: always

  # CrateDB Node 3
  crate-node3:
    image: crate:latest
    container_name: crate-node3
    command: >
      crate
      -Cnetwork.host=_site_
      -Ccluster.name=crate-cluster
      -Cnode.name=crate-node3
      -Cdiscovery.seed_hosts=crate-node1,crate-node2
      -Ccluster.initial_master_nodes=crate-node1,crate-node2,crate-node3
      -Cgateway.expected_data_nodes=3
      -Cgateway.recover_after_data_nodes=2
    restart: always

1. 설정 주입 방식: -C

• 문법: -C[키]=[값] (예: -Ccluster.name=my-cluster)
• 설명: CrateDB 설정 파일(crate.yml) 수정 없이 실행 시점에 설정 주입
• 비유: Java 애플리케이션의 -D 시스템 프로퍼티 주입과 동일 원리

2. 네트워크 및 식별 (Network & Identity)

-Cnetwork.host=_site_

• 설명: CrateDB 특수 변수 _site_ 사용. 컨테이너의 사설 IP(Private IP) 자동 감지 및 바인딩
• 목적: 동일 네트워크 내 다른 노드 간 통신 허용 (기본값 localhost는 외부 접근 불가)

-Ccluster.name=crate-cluster

• 설명: 클러스터 고유 식별자 (팀 이름)
• 주의: 클러스터 내 모든 노드의 값이 완벽하게 동일해야 함

-Cnode.name=crate-node1

• 설명: 각 노드를 구분하는 고유 식별자
• 목적: 장애 발생 시 로그 분석 및 문제 노드 식별

3. 디스커버리 및 마스터 선출 (Discovery)

-Cdiscovery.seed_hosts=crate-node2,crate-node3

• 의미: 초기 연결 대상 목록 (친구 전화번호부)
• 설명: 클러스터 시작 시 서로를 탐색(Discovery)하여 그룹을 형성하기 위한 피어(Peer) 주소

-Ccluster.initial_master_nodes=node1,node2,node3

• 의미: 초기 마스터 선출 자격 노드 목록
• 목적: 스플릿 브레인(Split-Brain) 방지 (네트워크 단절 시 마스터가 여러 개 생기는 현상 차단)

4. 데이터 안정성 및 복구 (Gateway & Recovery)

-Cgateway.expected_data_nodes=3

• 의미: 데이터 복구 시작을 위한 최소 노드 수 (정원 확인)
• 동작: 3개 노드가 모두 감지될 때까지 데이터 복구 대기
• 목적: 성급한 데이터 이동 방지 및 데이터 정합성 보장

-Cgateway.recover_after_data_nodes=2

• 의미: 서비스 활성화를 위한 최소 노드 수 (과반수)
• 동작: 과반수(2개) 이상 연결 시 클러스터 활성화 및 서비스 시작
• 효과: 일부 노드 장애 시에도 전체 서비스 중단 방지 (고가용성/HA)

백엔드 개발하다 보면 Controller, Service, Repository 계층 구조에 익숙해짐. 근데 비즈니스 로직이 복잡해질수록 Service가 비대해지거나, Controller가 너무 많은 Service를 호출하는 문제가 발생함.

이럴 경우 사용해야 하는 것이 파사드(Facade) 레이어. 실무에서 파사드 패턴을 도입해야 하는 확실한 타이밍 3가지를 정리해 봄.

1. 파사드(Facade)란?

건물의 정면(출입구)을 의미하는 단어처럼, 복잡한 내부 로직을 감추고 외부(Controller)에는 깔끔한 인터페이스만 보여주는 역할을 함.

핵심 역할: Controller와 여러 Service 사이의 중간 조율자 (Orchestrator)

2. 언제 써야 할까? (도입 기준 3가지)

Case 1. 컨트롤러가 너무 많은 서비스를 의존할 때

하나의 API 요청을 처리하기 위해 3~4개의 Service를 호출해야 한다면, Controller가 과도한 책임을 지고 있다는 신호임.

• Before (Controller가 바쁨): Controller가 OrderService, PaymentService, DeliveryService를 다 주입받아서 순서대로 호출함. 로직이 Controller에 노출됨.
• After (Facade 도입): Controller는 OrderFacade 하나만 알고 있음. "주문해줘"라고 요청하면 끝.

Case 2. 서비스 간의 순환 참조(Circular Dependency)를 끊을 때

개발하다 보면 UserService가 PointService를 참조하고, 반대로 PointService가 UserService를 참조해야 하는 상황이 옴. 이때 서로 import 하면 순환 참조 에러가 발생함.

이때 파사드가 두 서비스를 위에서 내려다보며 조율하면, 서비스끼리는 서로 몰라도 되므로 순환 참조가 깔끔하게 해결됨.

Case 3. 트랜잭션 단위가 여러 서비스에 걸쳐 있을 때

여러 서비스의 로직이 '전부 성공하거나, 전부 실패해야 하는(Atomic)' 경우임. 개별 Service에 트랜잭션을 거는 것만으로는 부족할 때, 파사드 메서드에 @Transactional을 걸어 전체 흐름을 하나의 트랜잭션으로 묶어주기 좋음.

3. 코드로 보는 Before & After (Python)

사용자가 '상품 구매'를 요청했을 때의 흐름 비교.

Before: Controller가 모든 로직을 제어

Controller가 비즈니스 흐름(재고 확인 -> 결제 -> 알림)을 다 알고 있음. 코드가 지저분하고 재사용이 어려움.

# controller.py

class OrderController:
    def __init__(self, inventory_svc, payment_svc, noti_svc):
        self.inventory_svc = inventory_svc
        self.payment_svc = payment_svc
        self.noti_svc = noti_svc

    def order(self, request):
        # 1. 재고 감소
        self.inventory_svc.decrease(request.product_id)

        # 2. 결제 시도
        self.payment_svc.pay(request.user_id, request.amount)

        # 3. 알림 발송
        self.noti_svc.send(request.user_id, "주문 완료")

        return "Success"

After: Facade 레이어 도입

Controller는 단순해지고, 비즈니스 흐름의 조합은 Facade가 전담함.

# facades/order_facade.py

class OrderFacade:
    def __init__(self, inventory_svc, payment_svc, noti_svc):
        self.inventory_svc = inventory_svc
        self.payment_svc = payment_svc
        self.noti_svc = noti_svc

    # 여러 서비스의 흐름을 하나의 트랜잭션으로 관리하기 용이함
    def process_order(self, user_id, product_id, amount):
        self.inventory_svc.decrease(product_id)
        self.payment_svc.pay(user_id, amount)
        self.noti_svc.send(user_id, "주문 완료")

# controller.py

class OrderController:
    def __init__(self, order_facade):
        self.order_facade = order_facade

    def order(self, request):
        # 깔끔해진 컨트롤러
        self.order_facade.process_order(
            request.user_id, 
            request.product_id, 
            request.amount
        )
        return "Success"

0. 사용한 계기

회사에서 대규모 로그 데이터에 대한 활용방안을 논의하다가
로그 데이터를 학습 데이터로 전환하여 활용하고
해당 데이터로 예측을 해보는 것에 대하여

1. MindsDB란 ?

• SQL 인터페이스를 통해 데이터베이스 내/외부 데이터로 예측 모델을 구축하고 쿼리할 수 있게 해주는 오픈 소스 플랫폼

2. 환경 설정 및 시작

1. Git 저장소 복제

git clone https://github.com/mindsdb/mindsdb.git

2. Docker 이미지 빌드 실행

sudo docker build -t mindsdb:ltscpu .

3. 컨테이너 실행

docker run -p [외부_포트]:47334 
-e MINDSDB_API_PORT=47334 -d mindsdb:ltscpu

4. MindsDB Studio

Logstash를 사용하여 ElasticSearch에 2억건의 데이터를 indexing 과정에 OutOfMemoryError가 나옴 CrateDB는 memory.breaker.limit 설정으로 각 쿼리에서 사용할 수 있는 메모리 상한선을 두고 있는데그 허용한도를 넘어버림

ERROR: [query] Data too large, data for [mergeOnHandler: 1] 
would be [1288635950/1.2gb], 
which is larger than the limit of [1288490188/1.1gb]

해결: JDBC 쿼리를 페이징 처리

# logstash.conf 파일에 아래와 같은 페이징 처리를 함
  jdbc_paging_enabled => true
  jdbc_page_size => 10000

정리

Logstash가 내부적으로 페이징 쿼리를 자동 생성하여 
한 번에 너무 많은 데이터를 가져오지 않도록 하여 처리

해당 방법은 데이터 양이 많을수록 OFFSET이 커져서 쿼리 성능이 급격히 나빠질 수 있음

이번 indexing 작업은 인스턴스 성격임으로 해당 방식으로 해결

기존의 회사 솔루션에 golang으로 만들어진 검색엔진이 처리하는 데이터가 많으면 느리다 라는 사용자의 요구사항으로 인해 ElasticSearch를 도입해보려고 함

1. 엘라스틱서치 기본 개념

1. 오픈소스 기반의 분산형 검색 및 분석 엔진

2. 텍스트 기반의 데이터를 빠르게 검색, 필터, 집계

3. 기본적으로 JSON 기반의 RESTful API로 동작

4. 내부적으로는 Apache Lucene을 사용
 - Apache Lucene이란? 
     자바(Java)로 작성된 풀텍스트 검색 엔진 라이브러리

2. 왜 사용하는가

 역색인(inverted index) 이라는 구조로 검색어 위치를 기억해서 매우 빠름

3. 사용 사례

1. 검색창 자동완성
2. 로그 분석
3. 추천 시스템

4. 기본 용어 정리

1. Index (인덱스): 
    데이터가 저장되는 공간. RDBMS의 데이터베이스에 해당

2. Document (문서): 
    실제로 저장되는 JSON 형태의 단일 데이터 (RDB의 row)

3. Field (필드):
    Document 안의 key (RDB의 column)

4. Mapping:
    필드에 대한 스키마 정의

5. Inverted Index:
    검색을 빠르게 하기 위한 구조. 단어 -> 문서 ID 매핑 구조

6. Cluster:
    Elasticsearch 전체 시스템 단위. 하나 이상의 노드로 구성

7. Node:
    Elasticsearch 인스턴스 1개 (보통 컨테이너 1개)

8. Shard:
    인덱스를 물리적으로 분할한 단위. 실제 데이터를 저장

9. Primary Shard:
    실제 데이터를 저장하는 주 샤드

10. Replica Shard:
    Primary의 복제본. 장애 대비 및 읽기 처리

11. Routing:
    어떤 문서를 어떤 샤드에 넣을지 결정하는 해싱 로직

12. text:
    분석기를 거쳐 토큰화되어 저장됨. 자연어 검색에 적합

13. keyword:
    전체 문자열을 그대로 저장. 정렬/집계/필터에 적합

14. fields:
    한 필드를 text + keyword 같이 여러 타입으로 저장할 때 사용

15. doc_values:
    keyword 등 집계/정렬용 필드의 내부 디스크 구조


[Cluster]
  └─ [Node]
        └─ [Shard]   -> Primary / Replica
              └─ [Index Data (partial)]
                    └─ [Document]

5. 간단하게 흐름 정리

1. JSON 데이터를 Elasticsearch에 보내면 분석 -> 역색인 생성 -> 저장
    -> Indexing

    * 역색인(Inverted Index): "단어->문서 번호 목록" 으로 연결된 자료구조

2. 검색 요청 시 단어 분석 -> 색인에서 문서 찾기 -> 점수 계산 -> 결과 반환
    -> Search

ex)
"삼성전자는 반도체를 개발한다."
    1. 분석기(analyzer)가 단어 추출: -> ["삼성전자", "반도체", "개발"]

    2. 역색인에 저장:
      {
        "삼성전자": [문서1],
        "반도체": [문서1],
        "개발": [문서1]
      }

    3. 사용자가 "반도체 개발" 검색

    4. 검색어 분석 -> ["반도체", "개발"]

    5. 기존에 만들어진 역색인에서 찾음:
      반도체 -> 문서1, 문서5
      개발 -> 문서1, 문서2

    6. 공통 문서인 문서1을 우선적으로 반환

6. 개인적인 의문사항

1. Elastic Search 는 RDBMS의 테이블 개념이 없는가?
 - Elasticsearch는 스키마가 없는 문서 기반 저장소이기 때문에
  RDB의 Table처럼 명확히 정의된 구조가 없고, Index 안에 바로 Document들이 있음.

  ex)
    PUT /blog_posts
    {
      "mappings": {
        "properties": {
          "title":   { "type": "text" },
          "content": { "type": "text" },
          "author":  { "type": "keyword" }
        }
      }
    }
    -> 이런식으로 각각의 JSON 문서가 RDB의 한 "row"에 해당