Python on Yarang's Tech Lair

NATS JetStream으로 멀티-LLM 분산 오케스트레이터 구축하기

Fri, 08 May 2026 21:57:11 +0900

1편에서는 Claude, ZAI, Codex, Gemini 네 가지 AI를 같은 태스크에 동시에 돌리면서 발견한 모델별 제한 사항을 다뤘다. 이번 편은 “어떻게 그게 가능하도록 만들었나”—시스템 설계와 구현 이야기다.

시스템 개요

AgentForge는 세 가지 요소로 이루어진다.

[태스크 발행자]
 │ NATS JetStream publish
 ▼
[NATS 브로커] ─── af.worker.{id}.inbox
 │ JetStream consume (워커별 독립 스트림)
 ▼
[워커 폴러] × N (poller.py × 18개)
 │ LLM CLI 실행 (claude / codex / gemini)
 ▼
[결과 반환] af.task.{task_id}.completed

발행자가 NATS에 태스크를 올리면, 각 워커가 독립적으로 구독하고 있다가 자신의 inbox로 들어온 메시지를 받아 LLM CLI를 실행한다. 결과는 완료 주제로 다시 publish된다.

왜 NATS JetStream인가

메시지 브로커 선택지는 여러 개였다: Redis Streams, Kafka, RabbitMQ, NATS JetStream.

NATS JetStream을 선택한 이유:

단일 바이너리 — 별도의 런타임 없이 nats-server 하나로 동작한다. Kafka의 ZooKeeper나 RabbitMQ의 Erlang/OTP 의존성이 없다.
내장 영속성 — JetStream은 NATS 위에 올라가는 스트리밍 레이어로, 메시지를 파일시스템에 저장한다. 워커가 재시작되어도 처리 안 된 태스크가 유실되지 않는다.
NKey 기반 인증 — 워커별로 독립된 Ed25519 keypair를 발급할 수 있다. 한 워커가 침해되어도 다른 워커의 자격증명은 유효하다.
경량 — 단일 서버에서 메모리 사용량 ~30MB. 18개 워커를 연결해도 브로커 부하가 거의 없다.

핵심: poller.py의 백엔드 어댑터

워커의 핵심은 poller.py다. 이 파일 하나가 NATS 구독, LLM CLI 실행, 결과 반환을 모두 담당한다.

LLM별 실행 방식이 다르기 때문에, 백엔드 어댑터 딕셔너리로 분리했다.

_BACKENDS: dict[str, dict] = {
 "claude": {
 "bin": os.environ.get("CLAUDE_BIN", "/usr/local/bin/claude"),
 "tools": os.environ.get("ALLOWED_TOOLS", "Read,Edit,Write,Glob,Grep"),
 "model": os.environ.get("CLAUDE_MODEL", ""),
 },
 "codex": {
 "bin": os.environ.get("CODEX_BIN", "/usr/bin/codex"),
 "model": os.environ.get("CODEX_MODEL", ""),
 "sandbox": os.environ.get("CODEX_SANDBOX", "read-only"),
 },
 "gemini_cli": {
 "bin": os.environ.get("GEMINI_BIN", "/usr/bin/gemini"),
 "model": os.environ.get("GEMINI_MODEL", ""),
 },
}

MODEL_BACKEND 환경변수로 어떤 LLM을 쓸지 결정한다. 덕분에 동일한 poller.py 코드로 18개 워커가 각자 다른 LLM을 실행한다.

Claude 백엔드

async def run_claude(instructions: str, task_id: str) -> tuple[int, str]:
 cfg = _BACKENDS["claude"]
 cmd = [cfg["bin"], "--print", "--allowedTools", cfg["tools"]]
 if cfg.get("model"):
 cmd += ["--model", cfg["model"]]
 proc = await asyncio.create_subprocess_exec(*cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE)

--print 플래그가 핵심이다. Claude Code가 대화 모드가 아닌 비대화형 모드로 실행되어 stdout으로 결과를 반환하게 만든다.

ZAI 백엔드

ZAI는 Anthropic API 호환 엔드포인트를 제공하기 때문에 별도 백엔드가 없다. 환경변수 두 개로 라우팅을 바꾼다.

# /etc/agentforge/cc-zai-high-dev-01.env
ANTHROPIC_BASE_URL=<ZAI endpoint>
ANTHROPIC_AUTH_TOKEN=<ZAI API key>

systemd EnvironmentFile= 지시어로 이 파일을 주입하면, claude 바이너리가 ZAI 엔드포인트로 요청을 보낸다. 코드 변경 없이 환경변수만으로 다른 LLM 공급자를 연결하는 셈이다.

선언적 관리: fleet.yaml × servers.yaml

18개 워커를 수동으로 관리하는 건 비현실적이다. 두 개의 YAML 파일로 전체 인프라를 선언적으로 정의했다.

servers.yaml — 서버 인벤토리

servers:
 - name: worker-node-1
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

 - name: broker-host
 role: broker-host
 services: [nats-jetstream, postgres]

 - name: worker-node-2
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

fleet.yaml — 워커 배치

workers:
 - worker_id: cc-go-dev-01
 llm: claude-code
 model: claude-sonnet-4-6
 lang: go
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: true

 - worker_id: codex-py-dev-01
 llm: codex
 model: gpt-5.5
 lang: python
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

host 필드 하나를 바꾸면 워커가 다른 서버로 이동한다. enabled: false로 설정하면 배포 스크립트가 해당 워커를 중지한다.

워커 템플릿 시스템: provision_worker.py

워커를 새로 추가할 때마다 systemd 유닛 파일을 직접 작성하는 건 오류가 생기기 쉽다. Jinja2 템플릿 + 프로비저닝 스크립트로 자동화했다.

템플릿 구조

templates/
 systemd/
 claude.service.j2 # claude-code, ZAI 공용
 codex.service.j2 # OpenAI Codex
 gemini.service.j2 # Google Gemini CLI

claude.service.j2의 핵심 부분:

Environment=MODEL_BACKEND=claude
Environment=CLAUDE_BIN={{ claude_bin }}
{% if claude_model %}
Environment=CLAUDE_MODEL={{ claude_model }}
{% endif %}
{% if env_file %}
EnvironmentFile={{ env_file }}
{% endif %}
Environment=WORK_BASE={{ work_base }}
Environment=WORK_DIR={{ work_base }}/repo
Environment="{{ 'ALLOWED_TOOLS=' + allowed_tools }}"
Environment=CREATE_PR={{ 'true' if create_pr else 'false' }}
{% if create_pr and github_remote %}
Environment=GITHUB_REMOTE={{ github_remote }}
{% endif %}

ZAI 워커는 env_file 블록이 활성화되어 EnvironmentFile이 추가된다. PR 생성 워커는 github_remote가 주입된다. 나머지는 기본값을 쓴다.

provision_worker.py 사용법

# 미리보기 (실제 배포 없음)
python3 scripts/provision_worker.py --worker new-worker-id --dry-run

# 실제 배포 (NATS creds 발급 포함)
python3 scripts/provision_worker.py --worker new-worker-id --issue-creds

# fleet.yaml 전체 일괄 배포
python3 scripts/provision_worker.py --all

내부적으로 수행하는 작업:

fleet.yaml에서 워커 항목 읽기
servers.yaml에서 대상 호스트 읽기
Jinja2 템플릿 렌더링
SSH로 /etc/systemd/system/{worker_id}-poller.service 배포
워크 디렉터리 생성
systemctl daemon-reload && enable --now
(선택) nsc add user로 NATS NKey 발급 → creds 배포 → auth.conf 재생성

분산 호스트: 두 번째 서버에 워커 추가

모든 워커를 한 서버에서 돌리면 단일 장애점이 된다. 두 번째 호스트에 Claude 워커를 추가했다.

두 번째 호스트에서 NATS 브로커에 연결하는 방법은 autossh 터널이다.

[Unit]
Description=NATS 브로커 터널
After=network-online.target

[Service]
ExecStart=/usr/bin/autossh -N \
 -L 4222:127.0.0.1:4222 \
 -i /home/ubuntu/.ssh/id_ed25519 \
 broker-host
Restart=always
RestartSec=10

이 설정이 활성화된 상태에서 워커는 항상 nats://127.0.0.1:4222로 연결한다. 브로커 호스트 주소를 몰라도 된다. 터널만 살아있으면 어느 호스트에서든 동일하게 동작한다.

NATS 자격증명 운영 경험

구현 중 가장 복잡했던 부분은 NATS NKey 관리다.

NATS JetStream의 인증 구조는 계층적이다.

Operator (최상위 서명 기관)
 └── Account: SYS (시스템 계정)
 └── Account: Services (워커 계정)
 ├── User: cc-dev-01
 ├── User: cc-go-dev-01
 ├── User: codex-py-dev-01
 └── ...

각 워커는 독립된 User NKey를 가지고, Services 계정의 권한 범위(af.>, _INBOX.>, $JS.>) 내에서만 publish/subscribe할 수 있다.

신규 워커를 추가할 때 Operator의 signing key가 필요하다. 초기에 이 키의 백업을 만들지 않았다가 분실하는 사고가 있었다. 결과적으로 Operator를 전부 재생성하고 모든 워커의 creds를 일괄 교체했다. 서비스 다운타임은 약 60초.

# 재생성 절차
nsc add operator AgentForge
nsc add account SYS
nsc add account Services
for worker in cc-dev-01 cc-go-dev-01 ...; do
 nsc add user --account Services --name $worker \
 --allow-pub "af.>,_INBOX.>,$JS.>" \
 --allow-sub "af.>,_INBOX.>,$JS.>"
done
nsc generate config --mem-resolver --sys-account SYS > auth.new.conf

새 워커 추가: 전체 절차

이 시스템이 완성된 이후 새 워커를 추가하는 절차는 단순하다.

1단계: fleet.yaml에 항목 추가

- worker_id: my-new-worker
 llm: claude-code
 model: claude-haiku-4-5
 lang: multi
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

2단계: 미리보기

python3 scripts/provision_worker.py --worker my-new-worker --dry-run

3단계: 실제 배포

python3 scripts/provision_worker.py --worker my-new-worker --issue-creds

끝이다. 템플릿 렌더링, SSH 배포, NATS 자격증명 발급, 서비스 등록까지 한 명령으로 처리된다.

다음 단계

현재 시스템은 워커가 태스크를 독립적으로 처리하는 구조다. 앞으로 만들고 싶은 것:

라우팅 정책: 태스크 특성에 따라 적합한 워커를 자동 선택 (Go 코드 → claude-go-dev, 비용 최우선 → ZAI 경량 티어)
결과 비교 대시보드: fan-out 결과를 나란히 보여주는 UI
비용 추적: 워커별 API 호출 비용 집계

코드는 GitHub에 공개되어 있다.

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

Wed, 06 May 2026 09:00:48 +0900

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

최근 Hacker News에서 흥미로운 기사를 접했습니다. **[Computer Use is 45x more expensive than structured APIs]**라는 제목의 글입니다. Anthropic의 최신 기능인 ‘Computer Use’는 AI가 컴퓨터 화면을 보고 마우스와 키보드를 조작하여 사용자 대신 작업을 수행할 수 있게 해줍니다. 마치 철권(Tekken) 게임에서 AI가 플레이어를 대신해 콤보를 입력하는 것처럼 매우 매력적입니다.

하지만 이 기능의 구현 비용은 기존의 **Structured Output(JSON 모드 등)**을 사용할 때보다 무려 45배나 높다는 분석이 나왔습니다.

이번 포스트에서는 왜 이런 격차가 발생하는지, 그리고 우리가 개발하는 **Multi-Agent 시스템(예: ZeroClaw)**에서 이 비용 문제를 어떻게 지혜롭게 해결할 수 있을지 현실적인 코드와 함께 분석해 보겠습니다.

1. 비용 격차의 원인 분석

Computer Use (GUI 기반 접근)

‘Computer Use’는 본질적으로 VNC(RDP) 원격 제어와 유사합니다. AI는 매 턴마다 다음을 수행해야 합니다.

화면 캡처: 고해상도 이미지를 다운로드합니다. (토큰 비용 급증)
시각적 처리: 이미지를 이해하기 위해 대규모 Vision 모델을 실행합니다.
좌표 계산: 버튼의 위치를 픽셀 단위로 계산합니다.
액션 실행: 마우스 클릭/키보드 입력을 전송합니다.

이 과정에서 단순한 텍스트 응답 대신 수백만 개의 ‘시각적 토큰’이 소모됩니다.

Structured Output (API 기반 접근)

반면, 우리가 블로그 API 서버나 MCP(Model Context Protocol)를 통해 구성하는 전통적인 방식은 훨씬 효율적입니다.

텍스트 입력: 시스템 상태나 사용자 의도가 텍스트로 전달됩니다.
논리적 추론: LLM이 텍스트를 파싱하여 의사결정을 내립니다.
직접 호출: tool_use 블록을 통해 함수를 직접 실행합니다. (이미지 처리 불필요)

2. 실용적인 해결책: 하이브리드 아키텍처

모든 작업을 Computer Use로 처리하는 것은 낭비입니다. 우리는 ZeroClaw나 MCP 블로그 자동화 프로젝트에서 배운 **‘도구 분리의 원칙’**을 적용해야 합니다.

전략: 도구 사용 우선순위

1순위: Native API (Structured Output)
- 데이터베이스 조회, API 호출, 파일 생성 등 명확한 로직은 항상 함수 호출로 처리.
2순위: Browser Automation (Playwright/Selenium)
- 복잡한 DOM 조작이 필요하나, 백엔드 API가 없는 경우. (이미지보다 HTML 트리를 파싱하는 것이 저렴)
최후의 수단: Computer Use (Vision)
- 캡차가 있거나, 동영상 편집 프로그램처럼 DOM 접근이 불가능한 오래된 레거시 소프트웨어만 대상으로 함.

3. 코드 예제: 비용 최적화된 Agent 구현

Python을 사용하여 LLM이 API 호출(Structured)과 브라우저 제어(Browser)를 선택적으로 사용하도록 만드는 예제를 작성해 보겠습니다. Computer Use는 아직 특정 클라우드 환경에 종속되어 있으므로, 가장 현실적인 대안인 **Playwright(HTML 기반)**와 API 호출을 비교하는 코드를 소개합니다.

시나리오: 블로그 게시글 자동 발행

LLM 에이전트에게 “최신 기술 뉴스를 요약하고 내 블로그에 발행해"라고 요청한다고 가정해 봅시다.

구조적 접근 (Structured Output + API)

import json
from typing import Literal

# 1. 도구 정의 (API 방식)
tools = [
 {
 "type": "function",
 "function": {
 "name": "create_blog_post",
 "description": "블로그에 새 글을 발행합니다. (가장 저렴하고 빠름)",
 "parameters": {
 "type": "object",
 "properties": {
 "title": {"type": "string"},
 "content": {"type": "string"},
 "tags": {"type": "array", "items": {"type": "string"}}
 },
 "required": ["title", "content"]
 }
 }
 },
 {
 "type": "function",
 "function": {
 "name": "search_web_browser",
 "description": "웹 브라우저를 제어하여 정보를 검색합니다. (API가 없을 때 사용)",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string"}
 },
 "required": ["query"]
 }
 }
 }
]

# 2. 에이전트 실행 로직 (시뮬레이션)
def run_agent(user_query: str):
 # 단계 1: LLM에게 도구 사용 요청 (실제로는 OpenAI/Anthropic API 호출)
 # LLM 응답 시뮬레이션: create_blog_post 도구 선택
 llm_response = {
 "tool": "create_blog_post",
 "arguments": {
 "title": "Gemma 4 가속화 기술",
 "content": "구글의 최신 모델 Gemma은 멀티-토큰 예측을 통해...",
 "tags": ["AI", "Google"]
 }
 }

 # 단계 2: 로컬 함수 실행 (Vision 필요 없음)
 if llm_response['tool'] == 'create_blog_post':
 print(f"[API 실행] 블로그 글 발행: {llm_response['arguments']['title']}")
 # 실제로는 여기서 requests.post('https://blog-api.com/posts', ...) 호출
 return {"status": "success", "cost": "0.0001 USD"}

print(run_agent("블로그에 글 써줘"))

이 방식은 텍스트만 주고받으므로 매우 저렴합니다.

비구조적 접근 (Computer Use 시뮬레이션 - 비용 상승)

만약 우리가 블로그 API를 사용하지 않고 Computer Use로 웹 브라우저를 띄워 글을 쓴다고 상상해 보세요.

# Computer Use 방식의 의사코드 (비용 폭발 구간)
def run_computer_use_agent():
 # 1. 화면 캡처 (1024x768 이미지 -> 약 1,100 토큰 소모)
 screenshot = capture_screen()
 print(f"[Vision] 화면 분석 중... (토큰 1,100개 소모)")

 # 2. LLM 추론: "로그인 버튼을 찾아라"
 action = llm_vision_inference(screenshot, prompt="Find the login button")
 # 결과: {"x": 500, "y": 300, "action": "click"}
 print(f"[Action] 마우스 이동 및 클릭: {action}")

 # 3. 다시 화면 캡처 및 입력 필드 분석
 screenshot = capture_screen()
 print(f"[Vision] 입력 필드 분석 중... (토큰 1,100개 소모)")
 
 # ... (반복적인 캡처와 추론)
 return {"status": "success", "cost": "0.05 USD"} 
 # API 방식(0.0001 USD) 대비 약 500배 비용 발생 가능

4. ZeroClaw 및 MCP 아키텍처 적용 가이드

우리가 진행 중인 **ZeroClaw(고성능 Rust 에이전트)**나 Discord MCP 프로젝트에서 이 원칙을 적용하면 다음과 같은 설계가 나옵니다.

MCP (Model Context Protocol) 표준 준수:
- 가능한 모든 자원(파일 시스템, 데이터베이스, 클라우드 리소스)을 MCP Server로 노출시켜 LLM이 Structured JSON으로 제어하게 하십시오.
- 예: Discord 메시지를 보낼 때, 브라우저를 띄우는 것이 아니라 discord_mcp.send_message() 함수를 호출하도록 유도합니다.
Prompt Engineering:
- 시스템 프롬프트에 명확히 선언하십시오.
- “당신은 화면을 보는 것이 아니라 도구를 호출해야 합니다. 사용자의 요청을 처리하기 위해 먼저 available_tools 리스트를 확인하고, 함수 호출이 가능한지 우선 확인하십시오.”
Fallback 메커니즘:
- MCP Server나 API가 죽었을 때만, 혹은 반드시 시각적 확인이 필요할 때만 ‘Computer Use’ 또는 ‘Browser Automation’ 에이전트를 깨우는 2단계 구조를 만드십시오.

5. 결론

AI 에이전트를 개발할 때 ‘Computer Use’는 마치 ‘스위스 군용 칼’과 같습니다. 모든 것을 할 수 있지만, 나사를 하나 조일 때마다 거대한 칼을 꺼내면(화면을 캡처면) 비용이 막대합니다.

우리는 **‘적재적소’**의 도구를 사용해야 합니다. 대부분의 작업은 **Structured Output(API)**으로 해결하고, 정말 어쩔 수 없는 상황에만 Vision/GUI 기능을 사용하는 전략을 취한다면, 45배의 비용 차이를 우리의 이익으로 돌릴 수 있을 것입니다.

앞으로 진행될 ZeroClaw 프로젝트의 통신 프로토콜 설계에서도 이 비용 효율성을 최우선 가이드라인으로 삼겠습니다.

[blog-api-server] 모니터링 대시보드 및 알림 시스템 구축

Tue, 03 Mar 2026 14:53:47 +0900

[blog-api-server] 모니터링 대시보드 및 알림 시스템 구축

개요

blog-api-server에 프로메테우스 기반 모니터링 시스템과 Slack/Email 알림 기능을 추가하여 서버 상태를 실시간으로 추적하고 문제 발생 시 즉시 대응할 수 있게 되었습니다.

모니터링 아키텍처

flowchart TB
 A[HTTP Request] --> B[MonitoringMiddleware]
 B --> C[Request Logging]
 B --> D[PrometheusMiddleware]
 D --> E[Metrics Collection]
 C --> F[AlertManager]
 E --> F
 F --> G{Threshold Check}
 G -->|Over Threshold| H[Slack Webhook]
 G -->|Critical| I[Email Alert]
 G -->|Normal| J[Log Only]
 K[Prometheus Server] --> L[/metrics/prometheus]
 M[Dashboard] --> N[/dashboard]

Prometheus 메트릭

기본 HTTP 메트릭

메트릭명	타입	라벨	설명
`http_requests_total`	Counter	method, endpoint, status	총 HTTP 요청 수
`http_request_duration_seconds`	Histogram	method, endpoint	요청 처리 시간 분포
`http_errors_total`	Counter	method, endpoint, status	총 에러 수
`active_requests`	Gauge	-	현재 활성 요청 수

비즈니스 메트릭

메트릭명	타입	라벨	설명
`git_operations_total`	Counter	operation, status	Git 작업 수
`git_operation_duration_seconds`	Histogram	operation	Git 작업 소요 시간
`translation_requests_total`	Counter	source_lang, target_lang, status	번역 요청 수
`translation_duration_seconds`	Histogram	-	번역 소요 시간
`post_operations_total`	Counter	operation, language, status	포스트 작업 수

메트릭 수집 코드

# prometheus_exporter.py
from prometheus_client import Counter, Histogram, Gauge

http_requests_total = Counter(
 'http_requests_total',
 'Total HTTP requests',
 ['method', 'endpoint', 'status']
)

http_request_duration_seconds = Histogram(
 'http_request_duration_seconds',
 'HTTP request latency',
 ['method', 'endpoint']
)

# 미들웨어에서 자동 수집
class PrometheusMiddleware(BaseHTTPMiddleware):
 async def dispatch(self, request: Request, call_next):
 start_time = time.time()
 response = await call_next(request)
 duration = time.time() - start_time

 http_requests_total.labels(
 method=request.method,
 endpoint=request.url.path,
 status=response.status_code
 ).inc()

 http_request_duration_seconds.labels(
 method=request.method,
 endpoint=request.url.path
 ).observe(duration)

알림 시스템

알림 규칙

규칙명	조건	심각도	쿨다운
High Error Rate	error_rate > 5%	WARNING	5분
Critical Error Rate	error_rate > 20%	CRITICAL	1분
Slow Response Time	avg_response_time > 2000ms	WARNING	10분
High Slow Request Rate	slow_request_rate > 10%	WARNING	5분

알림 채널

Slack Webhook

모든 심각도 수준 지원
색상으로 심각도 표현 (INFO: 녹색, WARNING: 주황, ERROR: 빨강, CRITICAL: 짙은 빨강)

Email

CRITICAL 수준만 전송
SMTP 기반 이메일 발송

AlertManager 코드

# alerting.py
class AlertManager:
 def check_and_alert(self, metrics: Dict[str, Any]):
 for rule in self.rules:
 if rule.should_trigger(metrics):
 self._send_alert(rule, metrics)

 def _send_alert(self, rule: AlertRule, metrics: Dict[str, Any]):
 message = f"""
Alert Rule: {rule.name}
Condition: {rule.condition}

Current Metrics:
- Total Requests: {metrics.get('total_requests', 0)}
- Error Count: {metrics.get('error_count', 0)}
- Error Rate: {metrics.get('error_rate_percent', 0)}%
- Slow Requests: {metrics.get('slow_request_count', 0)}
"""
 self.slack.send(
 title=f"Alert: {rule.name}",
 message=message.strip(),
 severity=rule.severity
 )

대시보드 구성

모니터링 엔드포인트

경로	인증	설명
`/health`	불필요	서버 상태 확인
`/metrics`	필요	JSON 형식 메트릭
`/metrics/prometheus`	불필요	Prometheus 형식 메트릭
`/metrics/reset`	필요	메트릭 초기화
`/dashboard`	불필요	웹 대시보드
`/alerts/rules`	필요	알림 규칙 목록
`/alerts/send`	필요	수동 알림 전송

요청 추적 미들웨어

# middleware.py
class MonitoringMiddleware(BaseHTTPMiddleware):
 async def dispatch(self, request: Request, call_next):
 request_id = str(uuid.uuid4())
 start_time = time.time()

 response = await call_next(request)
 process_time = (time.time() - start_time) * 1000

 # 응답 헤더에 추적 정보 추가
 response.headers["X-Process-Time"] = f"{process_time:.2f}"
 response.headers["X-Request-ID"] = request_id

 return response

환경 변수 설정

# Slack 알림
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# Email 알림
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
ALERT_FROM_EMAIL=your-email@gmail.com
ALERT_TO_EMAILS=admin@example.com,ops@example.com

# 임계값 설정
SLOW_REQUEST_THRESHOLD=1000 # 1초
VERY_SLOW_THRESHOLD=3000 # 3초
MAX_BODY_LOG_LENGTH=1000

향후 계획

Grafana 통합: Prometheus 데이터를 Grafana 대시보드로 시각화
알림 규칙 동적 구성: 런타임에 알림 규칙 추가/제거 API
메트릭 보관: 장기 메트릭 데이터 저장 및 분석
Health Check 강화: 의존 서비스(Git, LLM) 상태 확인

결론

프로메테우스 기반 모니터링과 Slack/Email 알림 시스템을 통해 서버 상태를 실시간으로 모니터링하고 문제 발생 시 즉시 대응할 수 있는 인프라가 구축되었습니다.

영어 버전: English Version

[Discord Decision MCP] 아키텍처 설계문서

Mon, 02 Mar 2026 21:36:30 +0900

Discord Decision MCP — 아키텍처 설계문서

1. 프로젝트 개요

1.1 목적

Claude Code가 tmux Teammate 모드로 자율 작업 중, 사용자 결정이 필요한 시점에 Discord를 통해 질문하고 응답을 받아 작업을 재개하는 MCP (Model Context Protocol) 서버입니다.

1.2 핵심 특징

특징	설명
프로젝트당 Bot 1개	각 프로젝트는 독립된 Discord Bot 사용
무한 대기 기본값	Timeout 없이 사용자 응답 대기 (Claude가 독단 진행 금지)
상태 영속화	프로세스 재시작 후에도 대기 상태 복원
한국어 친화적	한글 선택지, Yes/No 응답 지원
MCP 기반 통신	모든 Discord 통신은 MCP Tool을 통해 이루어짐

1.3 버전 정보

버전: 1.0.0
Python 요구사항: >= 3.11
MCP 프레임워크: FastMCP >= 0.1.0

2. 디렉토리 구조

discord-decision/
├── discord_mcp/ # 메인 패키지
│ ├── __init__.py
│ ├── server.py # MCP 서버 진입점
│ ├── config.py # 환경변수 설정 관리
│ │
│ ├── bot/ # Discord API 클라이언트
│ │ ├── __init__.py
│ │ ├── client.py # REST API 클라이언트 (httpx)
│ │ └── gateway.py # WebSocket 게이트웨이 (수신 전용)
│ │
│ ├── decision/ # 결정 요청 관리
│ │ ├── __init__.py
│ │ ├── manager.py # 결정 요청 생명주기 관리
│ │ ├── poller.py # Discord Polling 및 응답 대기
│ │ ├── parser.py # 사용자 응답 파싱
│ │ └── state.py # 상태 영속화 (JSON 파일)
│ │
│ ├── tools/ # MCP Tools 구현
│ │ ├── __init__.py
│ │ ├── ask.py # discord_ask_decision
│ │ ├── notify.py # discord_notify
│ │ ├── report.py # discord_report_progress
│ │ ├── status.py # discord_check_pending
│ │ ├── inbox.py # discord_read_inbox, discord_clear_inbox
│ │ └── _templates.py # Discord 메시지 템플릿
│ │
│ └── daemon/ # 감시 데몬
│ ├── __init__.py
│ ├── watcher.py # Discord 채널 감시 (discord-watch CLI)
│ └── inbox.py # Inbox 파일 관리
│
├── scripts/ # 유틸리티 스크립트
│ └── start-discord-watch.sh
│
├── tests/ # 테스트 스위트
│ ├── __init__.py
│ ├── test_parser.py
│ └── test_state.py
│
├── CLAUDE.md # Claude Code 프로젝트 지침
├── README.md # 프로젝트 설명
├── pyproject.toml # 프로젝트 설정 및 의존성
└── mcp.json.example # MCP 설정 예시

3. 주요 모듈 설명

3.1 서버 진입점 (`server.py`)

역할: FastMCP 서버 생성 및 MCP Tool 등록

mcp = FastMCP(name="discord-decision-mcp")
# Tool 등록
mcp.tool()(discord_ask_decision)
mcp.tool()(discord_notify)
mcp.tool()(discord_report_progress)
mcp.tool()(discord_check_pending)
mcp.tool()(discord_read_inbox)
mcp.tool()(discord_clear_inbox)

실행 방법:

discord-mcp # 또는 python -m discord_mcp.server

3.2 설정 관리 (`config.py`)

역할: 환경변수에서 설정값 로드

환경변수	설명	기본값
`DISCORD_BOT_TOKEN`	Discord Bot Token (“Bot " 접두사 포함)	필수
`DISCORD_CHANNEL_ID`	기본 질문 채널 ID	필수
`PROJECT_NAME`	question_id 생성에 사용	“project”
`PENDING_DIR`	상태 파일 저장 경로	`~/.claude/pending_decisions`
`POLL_INTERVAL_SECONDS`	Discord polling 간격 (초)	5

3.3 Discord API 클라이언트 (`bot/`)

3.3.1 REST API 클라이언트 (`client.py`)

역할: Discord REST API 호출 (httpx 기반)

주요 메서드:

class DiscordClient:
 async def send_message(channel_id, content, embeds=None)
 async def get_messages(channel_id, after=None, limit=50)
 async def create_thread(channel_id, name, first_message)
 async def archive_thread(thread_id)

특징:

Rate limit 자동 처리 (429 응답 시 재시도)
싱글턴 패턴 (get_client())

3.3.2 WebSocket 게이트웨이 (`gateway.py`)

역할: Discord Gateway WebSocket 연결 (수신 전용)

특징:

MESSAGE_CREATE 이벤트 실시간 수신
Polling 방식의 지연을 5초 → 즉시로 단축
Gateway 없이도 시스템 정상 동작 (Polling fallback)
자동 재연결 (Exponential backoff)

class GatewayClient:
 async def run() # 이벤트 수신 시작
 async def stop() # 연결 종료

3.4 결정 요청 관리 (`decision/`)

3.4.1 DecisionManager (`manager.py`)

역할: 결정 요청의 전체 생명주기 조율

class DecisionManager:
 async def ask(question, context, options, timeout_seconds, thread_id) -> PollResult
 async def restore_pending() -> list[DecisionState]

흐름:

중복 질문 확인
Thread 생성 (또는 기존 Thread 재사용)
상태 파일 생성 (~/.claude/pending_decisions/{question_id}.json)
Poller 실행하여 응답 대기
SIGHUP 시그널 핸들러로 disconnected 상태 표시

3.4.2 DecisionPoller (`poller.py`)

역할: Discord 채널을 polling하여 응답 대기

class DecisionPoller:
 async def wait(state: DecisionState) -> PollResult

특징:

기본값: 무한 대기 (timeout_seconds=None)
tmux pane에 실시간 대기 상태 표시 (ANSI escape)
모호한 응답 시 최대 2회 재질문

3.4.3 응답 파서 (`parser.py`)

역할: 사용자 Discord 응답 파싱

지원 패턴:

선택지 매칭: “A”, “a”, “A번”, “A로 해줘”, “1”, “1번”
긍정/부정: “yes”, “네”, “예”, “no”, “아니요”
자연어: 15자 이상 또는 한글 3자 이상

def parse_response(text: str, options: list[str]) -> ParseResult
def build_clarify_message(...) -> str # 재질문 메시지 생성

3.4.4 상태 저장소 (`state.py`)

역할: 결정 요청 상태를 JSON 파일로 영속화

상태 파일 위치: ~/.claude/pending_decisions/{question_id}.json

class DecisionState(BaseModel):
 question_id: str
 project: str
 question: str
 context: str
 options: list[str]
 timeout_seconds: float | None
 thread_id: str
 message_id: str
 asked_at: str
 status: Literal["pending", "disconnected", "resolved", "aborted", "timeout"]
 clarify_attempts: int
 resolved_at: str | None
 resolution: str | None
 selected_option: str | None

class StateStore:
 def save(state: DecisionState)
 def load(question_id: str) -> DecisionState | None
 def load_all_pending() -> list[DecisionState]
 def resolve(question_id, resolution, selected_option)
 def is_duplicate(question: str) -> bool

3.5 MCP Tools (`tools/`)

Tool	블로킹	설명
`discord_ask_decision`	✅	사용자 결정 요청
`discord_notify`	❌	진행 상황 알림
`discord_report_progress`	❌	작업 완료 리포트
`discord_check_pending`	❌	미해결 질문 확인
`discord_read_inbox`	❌	Inbox 메시지 조회
`discord_clear_inbox`	❌	Inbox 메시지 삭제

3.6 감시 데몬 (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

역할: Discord 채널을 감시하여 새 메시지를 inbox 파일에 기록

실행 방법:

discord-watch --interval 10
# 또는
tmux new-session -d -s discord-watch 'uv run discord-watch'

특징:

지정된 채널(들)을 주기적으로 polling
새로운 사용자 메시지 감지 시 inbox에 기록
tmux pane에 상태 표시

3.6.2 InboxStore (`inbox.py`)

역할: Discord 메시지를 저장하는 JSON 파일 기반 저장소

Inbox 파일 위치: ~/.claude/discord_inbox.json

class InboxMessage:
 message_id: str
 channel_id: str
 thread_id: str | None
 author: str
 author_id: str
 content: str
 timestamp: str
 read: bool

class InboxStore:
 def add_message(msg: InboxMessage)
 def get_unread() -> list[InboxMessage]
 def mark_read(message_id: str)
 def clear_read() # 읽은 메시지 삭제

4. 데이터 흐름도

4.1 결정 요청 흐름

┌─────────────────┐
│ Claude Code │
└────────┬────────┘
 │ discord_ask_decision()
 ▼
┌─────────────────────────────────────┐
│ MCP Server (server.py) │
│ ┌───────────────────────────────┐ │
│ │ DecisionManager.ask() │ │
│ │ 1. 중복 확인 │ │
│ │ 2. Thread 생성 │ │
│ │ 3. 상태 파일 저장 │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 ▼
┌─────────────────────────────────────┐
│ DecisionPoller.wait() │
│ ┌───────────────────────────────┐ │
│ │ Polling 루프 │ │
│ │ 1. tmux 상태 업데이트 │ │
│ │ 2. Discord API 호출 │ │
│ │ 3. 응답 파싱 │ │
│ │ 4. 모호하면 재질문 │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 │
 ┌─────────┴─────────┐
 ▼ ▼
┌───────────────────┐ ┌──────────────────┐
│ Discord REST API │ │ Discord Thread │
│ (client.py) │ │ │
└───────────────────┘ └────────┬─────────┘
 │
 ┌────────▼────────┐
 │ 사용자 응답 │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ parser.py │
 │ - 선택지 매칭 │
 │ - 모호성 감지 │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ store.resolve()│
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ PollResult │
 │ 반환 │
 └─────────────────┘

4.2 감시 데몬 흐름

┌─────────────────────────────────────────────┐
│ DiscordWatcher (daemon/watcher.py) │
│ ┌───────────────────────────────────────┐ │
│ │ 1. 초기 메시지 ID 설정 │ │
│ │ 2. 주기적 Polling (기본 10초) │ │
│ │ 3. 새 메시지 감지 │ │
│ │ 4. InboxStore.add_message() │ │
│ └───────────────────┬───────────────────┘ │
└──────────────────────┼──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ ~/.claude/discord_inbox.json │
│ { │
│ "last_message_id": "...", │
│ "messages": [ │
│ { "message_id": "...", ... } │
│ ] │
│ } │
└──────────────────────┬──────────────────────┘
 ▲
 │ discord_read_inbox()
┌──────────────────────┴──────────────────────┐
│ Claude Code │
└─────────────────────────────────────────────┘

4.3 세션 복원 흐름

┌─────────────────────────────────────────────┐
│ Claude Code 세션 시작 │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ discord_check_pending() │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ DecisionManager.restore_pending() │
│ ┌───────────────────────────────────────┐ │
│ │ 1. ~/.claude/pending_decisions/*.json │ │
│ │ 2. Discord API로 Thread 확인 │ │
│ │ 3. 답변 있으면 → 자동 해결 │ │
│ │ 4. 답변 없으면 → 재시작 알림 │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

5. MCP 도구 목록

5.1 discord_ask_decision

설명: 사용자 결정이 필요할 때 Discord Thread에 질문 전송 후 응답 대기 (블로킹)

파라미터:

이름	타입	필수	설명
`question`	string	✅	질문 내용
`context`	string	✅	현재 작업 상황
`options`	string[]	❌	선택지 목록 (빈 배열이면 자유 응답)
`timeout_seconds`	float	❌	대기 Timeout (null이면 무한 대기)
`thread_id`	string	❌	기존 Thread ID (null이면 새 Thread 생성)

반환값:

{
 "success": true,
 "answer": "A) 지금 실행",
 "selected_option": "A) 지금 실행",
 "question_id": "project_20260301_abc123",
 "timed_out": false,
 "aborted": false
}

5.2 discord_notify

설명: 진행 상황을 Discord에 알림 (논블로킹)

파라미터:

이름	타입	필수	설명
`message`	string	✅	알림 메시지
`level`	string	❌	info/warning/success/error (기본값: info)
`thread_id`	string	❌	전송할 Thread ID (null이면 기본 채널)

5.3 discord_report_progress

설명: 작업 완료 또는 단계 완료 시 결과 리포트 (논블로킹)

파라미터:

이름	타입	필수	설명
`title`	string	✅	리포트 제목
`summary`	string	✅	작업 결과 요약
`details`	string[]	❌	세부 항목 목록
`thread_id`	string	❌	전송할 Thread ID

5.4 discord_check_pending

설명: 세션 시작 시 미해결 질문 확인 (논블로킹)

파라미터: 없음

반환값:

{
 "has_pending": true,
 "pending_questions": [
 {
 "question_id": "project_20260301_abc123",
 "question": "배포할까요?",
 "thread_id": "1234567890",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending"
 }
 ]
}

5.5 discord_read_inbox

설명: Inbox에 저장된 메시지 조회 (논블로킹)

파라미터:

이름	타입	기본값	설명
`unread_only`	boolean	true	읽지 않은 메시지만 반환
`mark_read`	boolean	false	조회한 메시지를 읽음으로 표시

5.6 discord_clear_inbox

설명: Inbox 메시지 삭제 (논블로킹)

파라미터:

이름	타입	기본값	설명
`read_only`	boolean	true	읽은 메시지만 삭제

6. 의존성 정보

6.1 핵심 의존성

패키지	버전	용도
`fastmcp`	>= 0.1.0	MCP 서버 프레임워크
`httpx`	>= 0.27.0	비동기 HTTP 클라이언트
`websockets`	>= 12.0	WebSocket 클라이언트
`python-dotenv`	>= 1.0.0	환경변수 로드
`pydantic`	>= 2.0.0	데이터 모델 검증
`anyio`	>= 4.0.0	비동기 실행

6.2 개발 의존성

패키지	용도
`pytest`	테스트 프레임워크
`pytest-asyncio`	비동기 테스트 지원
`pytest-mock`	Mock 지원
`respx`	httpx mocking

6.3 CLI 명령어

discord-mcp # MCP 서버 실행
discord-watch # 감시 데몬 실행

7. 상태 파일 형식

7.1 결정 상태 파일

위치: ~/.claude/pending_decisions/{question_id}.json

{
 "question_id": "project_20260301_abc123",
 "project": "my-project",
 "question": "DB 마이그레이션을 실행할까요?",
 "context": "v1→v2 스키마 변경",
 "options": ["A) 지금 실행", "B) 스테이징 먼저", "C) 보류"],
 "timeout_seconds": null,
 "thread_id": "1234567890",
 "message_id": "0987654321",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending",
 "clarify_attempts": 0,
 "resolved_at": null,
 "resolution": null,
 "selected_option": null
}

7.2 Inbox 파일

위치: ~/.claude/discord_inbox.json

{
 "last_message_id": "1234567890",
 "messages": [
 {
 "message_id": "1234567890",
 "channel_id": "1234567890",
 "thread_id": null,
 "author": "username",
 "author_id": "1234567890",
 "content": "메시지 내용",
 "timestamp": "2026-03-01T00:00:00Z",
 "read": false
 }
 ]
}

8. 아키텍처 원칙

8.1 설계 원칙

싱글톤 패턴: DiscordClient, StateStore, InboxStore는 모듈 레벨 싱글턴
상태 영속화: 모든 결정 요청 상태는 파일로 영속화
무한 대기 기본값: Claude가 독단적으로 진행하지 않도록 timeout 기본값은 None
재질문 제한: 모호한 응답은 최대 2회까지만 재질문
Rate Limit 처리: Discord API 429 응답 시 자동 대기 후 재시도

8.2 에러 handling

상황	처리 방법
Discord API 429	자동 대기 후 재시도 (최대 5회)
WebSocket 연결 끊김	Exponential backoff로 재연결
응답 파싱 실패	최대 2회 재질문 후 중단
Timeout 발생	작업 중단 알림 후 aborted 상태
세션 끊김 (SIGHUP)	disconnected 상태로 저장

문서 버전: 1.0.0 마지막 수정: 2026-03-02

영어 버전: English Version

[blog-api-server] 로깅 개선 완료

Fri, 27 Feb 2026 23:48:07 +0900

API 서버 로깅 개선 완료

개요

블로그 API 서버에 상세 로깅을 추가하여 요청 처리 과정을 추적할 수 있게 되었습니다.

추가된 로깅

API 레벨 (`[API]` prefix)

요청 시작/종료
요청 파라미터
처리 시간

블로그 매니저 레벨 (`[BLOG_MANAGER]` prefix)

Git lock 획득/해제
동기화(Sync) 진행 상황
파일명 생성
파일 작성
Git commit/push 단계별 진행

Git 명령 레벨 (`[GIT]` prefix)

Git 명령어 실행 시작
명령어 완료 시간
에러 및 경고 메시지

수정된 문제들

LogRecord 예약 속성 충돌: filename, message 등 예약어를 post_filename, commit_msg로 변경
데드락 문제: commit_and_push에서 중복 lock 획득 제거
경로 오류: 한국어 포스트 경로를 content/post/로 수정

타이밍 분석 예시

Git pull: ~2.3초
파일 작성: ~1ms
Git commit: ~42ms
Git push: ~2.5초
총 요청 시간: ~4.8초

결론

상세 로깅을 통해 API 요청의 각 단계를 명확히 추적할 수 있게 되었으며, 문제 발생 시 원인 파악이 용이해졌습니다.

영어 버전: English Version

Python on Yarang's Tech Lair

NATS JetStream으로 멀티-LLM 분산 오케스트레이터 구축하기

시스템 개요

왜 NATS JetStream인가

핵심: poller.py의 백엔드 어댑터

Claude 백엔드

ZAI 백엔드

선언적 관리: fleet.yaml × servers.yaml

servers.yaml — 서버 인벤토리

fleet.yaml — 워커 배치

워커 템플릿 시스템: provision_worker.py

템플릿 구조

provision_worker.py 사용법

분산 호스트: 두 번째 서버에 워커 추가

NATS 자격증명 운영 경험

새 워커 추가: 전체 절차

다음 단계

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

1. 비용 격차의 원인 분석

Computer Use (GUI 기반 접근)

Structured Output (API 기반 접근)

2. 실용적인 해결책: 하이브리드 아키텍처

전략: 도구 사용 우선순위

3. 코드 예제: 비용 최적화된 Agent 구현

시나리오: 블로그 게시글 자동 발행

구조적 접근 (Structured Output + API)

비구조적 접근 (Computer Use 시뮬레이션 - 비용 상승)

4. ZeroClaw 및 MCP 아키텍처 적용 가이드

5. 결론

[blog-api-server] 모니터링 대시보드 및 알림 시스템 구축

[blog-api-server] 모니터링 대시보드 및 알림 시스템 구축

개요

모니터링 아키텍처

Prometheus 메트릭

기본 HTTP 메트릭

비즈니스 메트릭

메트릭 수집 코드

알림 시스템

알림 규칙

알림 채널

AlertManager 코드

대시보드 구성

모니터링 엔드포인트

요청 추적 미들웨어

환경 변수 설정

향후 계획

결론

[Discord Decision MCP] 아키텍처 설계문서

Discord Decision MCP — 아키텍처 설계문서

1. 프로젝트 개요

1.1 목적

1.2 핵심 특징

1.3 버전 정보

2. 디렉토리 구조

3. 주요 모듈 설명

3.1 서버 진입점 (server.py)

3.2 설정 관리 (config.py)

3.3 Discord API 클라이언트 (bot/)

3.3.1 REST API 클라이언트 (client.py)

3.3.2 WebSocket 게이트웨이 (gateway.py)

3.4 결정 요청 관리 (decision/)

3.4.1 DecisionManager (manager.py)

3.4.2 DecisionPoller (poller.py)

3.4.3 응답 파서 (parser.py)

3.4.4 상태 저장소 (state.py)

3.5 MCP Tools (tools/)

3.6 감시 데몬 (daemon/)

3.6.1 DiscordWatcher (watcher.py)

3.6.2 InboxStore (inbox.py)

4. 데이터 흐름도

4.1 결정 요청 흐름

4.2 감시 데몬 흐름

4.3 세션 복원 흐름

5. MCP 도구 목록

5.1 discord_ask_decision

5.2 discord_notify

5.3 discord_report_progress

5.4 discord_check_pending

5.5 discord_read_inbox

3.1 서버 진입점 (`server.py`)

3.2 설정 관리 (`config.py`)

3.3 Discord API 클라이언트 (`bot/`)

3.3.1 REST API 클라이언트 (`client.py`)

3.3.2 WebSocket 게이트웨이 (`gateway.py`)

3.4 결정 요청 관리 (`decision/`)

3.4.1 DecisionManager (`manager.py`)

3.4.2 DecisionPoller (`poller.py`)

3.4.3 응답 파서 (`parser.py`)

3.4.4 상태 저장소 (`state.py`)

3.5 MCP Tools (`tools/`)

3.6 감시 데몬 (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

3.6.2 InboxStore (`inbox.py`)

API 레벨 (`[API]` prefix)

블로그 매니저 레벨 (`[BLOG_MANAGER]` prefix)

Git 명령 레벨 (`[GIT]` prefix)