TIL

FastAPI + LangGraph AI Agent self-hosted 모니터링 플랫폼 비교(Langfuse vs Arize Phoenix)

2026-05-13T00:00:00+09:00

폐쇄망에서 FastAPI & LangGraph 를 활용한 AI Agent를 개발할 때, self-hosted 배포가 가능한 모니터링 플랫폼을 비교합니다.

1. Langfuse vs Arize Phoenix 선택 기준

LangGraph 연동 방식

Langfuse는 콜백 핸들러 방식으로 LangGraph와 연동합니다.

from langfuse.callback import CallbackHandler

handler = CallbackHandler()
graph.invoke(input, config={"callbacks": [handler]})

Phoenix는 OpenInference의 LangChainInstrumentor를 사용합니다. LangGraph는 별도의 instrumentation 패키지가 없으며, langchain-core를 공유 기반으로 사용하기 때문에 LangChain instrumentation으로 커버됩니다.

from openinference.instrumentation.langchain import LangChainInstrumentor
from phoenix.otel import register

tracer_provider = register(project_name="my-llm-app", auto_instrument=True)

기능 비교

항목	Langfuse	Arize Phoenix
LangGraph 공식 지원	콜백 핸들러	LangChain instrumentor 경유
Self-host 구성 요소	6개 (web, worker, PG, ClickHouse, Redis, Minio)	1~2개 (앱 + DB)
프롬프트 버전 관리	내장	없음
LLM 비용 자동 집계	O	O (SpanCostCalculator)
RAG 평가	O	O (강점)
수신 프로토콜	자체 HTTP API	OTLP 표준 (HTTP / gRPC)
DB	ClickHouse + PostgreSQL	SQLite 또는 PostgreSQL
외부 큐	Redis (BullMQ)	In-memory Queue

2. 기본 개념 정리

Trace와 Span

Trace: 유저 요청 하나의 전체 흐름
Span: 그 안의 개별 작업 단위 (LLM 호출, 툴 호출, DB 조회 등)

각 Span은 시작/종료 시간, 소요 시간, 성공/실패 여부, 입출력 메타데이터를 담습니다.

LangGraph 에이전트를 실행하면 노드 하나하나가 Span으로 기록됩니다.

Ingestion

SDK에서 모니터링 서버로 trace/span 데이터를 전송하는 행위 자체를 ingestion이라고 합니다.

3. Langfuse Self-hosted 아키텍처

구성 요소

Langfuse v3 self-hosted는 6개의 서비스로 구성됩니다.

├── langfuse-web     (port 3000 — UI + API)
├── langfuse-worker  (port 3030 — 비동기 처리)
├── ClickHouse       (8123, 9000 — OLAP 분석 DB)
├── MinIO / S3       (9090 — 오브젝트 스토리지)
├── Redis            (6379 — 큐 + 캐시)
└── PostgreSQL       (5432 — 트랜잭션 DB)

각 구성 요소의 역할

구성 요소	역할
langfuse-web (Next.js)	UI 콘솔 서빙, 모든 API 처리
langfuse-worker (Express)	비동기 이벤트 처리, LLM-as-a-Judge, 배치 export
PostgreSQL	유저, 조직, 프로젝트, API 키, 프롬프트 등 트랜잭션 데이터
ClickHouse	trace, observation, score 등 대용량 로그 데이터
Redis	BullMQ 이벤트 큐 + API 키/프롬프트 캐시
S3 / MinIO	raw 이벤트 원본, 멀티모달 미디어, 배치 export 파일

데이터 흐름

SDK
HTTP POST /api/public/ingestion
langfuse-web
S3에 raw 이벤트 저장
Redis에 S3 참조(경로)만 큐에 넣음
207 반환(HTTP Response)
langfuse-worker
Redis에서 S3 참조 꺼냄
S3에서 실제 데이터 읽어서 enriching (토큰/비용 계산 등)
ClickHouse에 씀

핵심은 web이 DB에 직접 쓰지 않는다는 것입니다. Redis 큐에는 S3 경로(참조)만 넘기고, 실제 데이터는 S3에 있습니다. 수신과 저장을 분리해서 트래픽이 몰려도 web이 죽지 않는 구조입니다.

langfuse-web vs langfuse-worker 분리 이유

Langfuse v3는 Event-Driven 백엔드 아키텍처를 채택했습니다. SDK에서 오는 HTTP 요청을 즉시 수신한 뒤 큐에 넣고 비동기로 처리합니다. 이를 통해 DB에 부하를 주지 않고 더 많은 요청을 처리할 수 있습니다.

v2는 단일 컨테이너 + PostgreSQL만으로 구성되었으나, 수백만 row의 tracing 데이터에서 병목이 발생해 v3에서 ClickHouse, Redis, S3, worker 컨테이너가 추가됐습니다.

S3 / MinIO 사용 목적

Langfuse는 S3를 세 가지 용도로 사용합니다.

Raw 이벤트 저장 (필수): SDK에서 들어오는 이벤트 원본을 그대로 저장. 모든 배포에서 필수 설정입니다. ClickHouse가 일시적으로 불가해도 이벤트 유실을 방지하는 복구용 백업이기도 합니다.
멀티모달 입출력 (선택): 이미지, 오디오 등 base64 인코딩된 미디어를 trace에 포함할 경우 SDK가 자동으로 S3에 업로드하고 trace에는 참조 문자열만 남깁니다.
배치 export (선택): UI에서 CSV/JSON 대용량 내보내기 시 사용합니다.

MinIO는 S3 API와 호환되는 오픈소스 오브젝트 스토리지 서버로, AWS 환경이라면 MinIO 없이 S3를 그대로 사용할 수 있습니다. Docker Compose / Helm 배포에서는 기본값으로 MinIO가 포함됩니다.

S3 데이터 삭제 정책

데이터 종류	삭제 시점
Raw 이벤트 (text)	S3 lifecycle 정책으로 직접 설정 (기본값 없음, Langfuse Cloud는 30일)
멀티모달 미디어	정책 설정 권장 안 함 (삭제 시 UI 참조 깨짐)
ClickHouse 데이터	Data Retention 기능으로 프로젝트별 설정 (최소 3일)

Data Retention 기능을 활성화하면 이벤트 만료 시 blob_storage_file_log 테이블을 참고해 S3의 해당 파일도 함께 삭제합니다.

Redis 역할 상세

BullMQ 이벤트 큐: web이 받은 이벤트의 S3 참조를 worker에게 전달
API 키 캐시: 모든 API 호출마다 DB를 조회하지 않도록 인메모리 캐싱(보통 환경변수에 적는 API KEY입니다.)
프롬프트 캐시: 자주 사용되는 프롬프트를 read-through 캐시로 빠르게 제공

4. Arize Phoenix Self-hosted 아키텍처

구성 요소

Phoenix는 단일 컨테이너로 구성됩니다.

├── Phoenix 컨테이너 (port 6006 — UI + HTTP OTLP)
│                   (port 4317 — gRPC OTLP)
└── SQLite 또는 PostgreSQL

데이터 흐름

SDK (openinference instrumentation)
 1. OTLP (HTTP: 6006/v1/traces 또는 gRPC: 4317)
Phoenix 단일 컨테이너
 2. In-memory Span Queue (최대 20,000개)
 3. BulkInserter (배치로 묶어서)
 4. SQLite 또는 PostgreSQL

Span Queue가 20,000개 한도에 도달하면 새로운 span 요청에 HTTP 429를 반환합니다.

스토리지

SQLite: 기본값. 로컬 개발 및 소규모 배포에 적합.
PostgreSQL: 프로덕션 권장. 동시 접근, 백업/복제 등 표준 DB 도구 활용 가능.

5. 구조 비교 요약

항목	Langfuse	Phoenix
컨테이너 수	6개	1개
큐 방식	Redis BullMQ (외부)	In-memory (내장, 20k 한도)
분석 DB	ClickHouse	없음 (PostgreSQL만 사용)
오브젝트 스토리지	S3 / MinIO (필수)	없음
수신 프로토콜	자체 HTTP API	OTLP 표준 (HTTP / gRPC)
운영 복잡도	높음	낮음
대규모 트래픽 대응	유리 (이벤트 드리븐 + ClickHouse)	불리 (큐 20k 한도)
Self-host 시작 난이도	높음	낮음 (컨테이너 1개)

6. 결론

FastAPI + LangGraph 실서비스 기준:

운영 안정성과 실시간 모니터링 & 대규모 트래픽이 중요하다면 → Langfuse
빠르게 띄우고 RAG 평가에 집중하고 싶다면 → Phoenix
이미 OpenTelemetry 인프라가 있다면 → Phoenix가 자연스럽게 연동됨(OTLP)

두 도구는 목적이 다르므로 병행 사용도 가능합니다. Phoenix로 로컬/스테이징 디버깅, Langfuse로 프로덕션 운영 모니터링을 나누는 방식도 실용적입니다.

개인적으로는 Self-hosted로 둘 다 띄워봤을 때, UI/UX적으로 Langfuse가 통계 그래프가 많이 제공되어 더 좋았습니다.

참고

Langfuse & Phoenix SDK 동작 원리 및 FastAPI 성능 영향 & 배포시 주의사항

2026-05-13T00:00:00+09:00

FastAPI + LangGraph 실서비스에 Langfuse 또는 Phoenix를 붙일 때 내부 동작을 이해하고 있으면 예상치 못한 문제를 피할 수 있습니다.
이 글은 두 SDK의 내부 구조, FastAPI에 미치는 성능 영향, 그리고 Gunicorn/Uvicorn 배포 환경에서의 주의사항을 정리합니다.

1. SDK는 FastAPI에 부하를 주는가?

Langfuse Python SDK

Langfuse SDK는 백그라운드 스레드 + 내부 큐 방식으로 동작합니다.

“It uses a worker Thread and an internal queue to manage requests to the Langfuse backend asynchronously. Hence, the SDK adds only minimal latency to your application.”

— Langfuse Python SDK 공식 문서

콜백이 호출되면 span 데이터를 내부 큐에 넣고 즉시 리턴합니다. 실제 네트워크 전송은 별도의 백그라운드 스레드가 담당합니다.

FastAPI 요청 처리 (메인)
    ↓ span 생성 → 내부 큐에 넣고 즉시 리턴
    ↓ 응답 반환

백그라운드 스레드 (별도)
    ↓ 큐에서 꺼내서 Langfuse 서버로 배치 전송

백그라운드 스레드의 전송 트리거 조건은 두 가지입니다.

조건	파라미터	기본값
이벤트 개수	`flush_at`	512개
시간 경과	`flush_interval`	5초

둘 중 먼저 충족되는 조건에 따라 배치 전송이 트리거됩니다.

참고: Langfuse Event Queuing/Batching 문서

Phoenix (OpenTelemetry BatchSpanProcessor)

Phoenix는 OpenTelemetry의 BatchSpanProcessor를 사용합니다.

“The BatchSpanProcessor is the recommended implementation for production. It buffers spans in a queue and exports them in batches using a background worker thread.”

— OpenTelemetry Python SDK DeepWiki

트리거 조건은 환경변수로 제어합니다.

조건	환경변수	기본값
span 개수	`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	512개
시간 경과	`OTEL_BSP_SCHEDULE_DELAY`	5000ms (5초)

주의: Phoenix register() 함수의 batch 파라미터 기본값은 False입니다. 프로덕션에서는 반드시 batch=True를 명시해야 합니다. 그렇지 않으면 SimpleSpanProcessor가 동작해서 span이 끝날 때마다 동기로 즉시 전송되어 FastAPI 응답 시간에 직접 영향을 줍니다.

# 프로덕션 권장 설정
from phoenix.otel import register

tracer_provider = register(
    project_name="my-app",
    batch=True,  # 반드시 명시
    auto_instrument=True,
)

참고: arize-phoenix-otel PyPI

2. GIL과 백그라운드 스레드

Python의 GIL(Global Interpreter Lock)로 인해 스레드가 여러 개여도 CPU 작업은 한 번에 하나만 실행됩니다. 하지만 백그라운드 스레드가 하는 작업 대부분은 네트워크 전송 대기(I/O)이며, GIL은 I/O 대기 중에는 자동으로 해제됩니다. 실제 CPU를 사용하는 구간(직렬화 등)만 GIL 경합이 발생하는데, 이 구간은 매우 짧습니다.

이론적으로 나노초 수준의 오버헤드가 누적될 수 있지만, FastAPI를 uvicorn으로 운영하는 async 환경에서는 GIL 경합 자체가 훨씬 줄어들어 체감 성능 저하로 이어지는 경우는 드뭅니다.

3. 백그라운드 스레드 구현

Langfuse SDK (v3/v4)

Langfuse SDK v3/v4는 span 전송을 위해 OpenTelemetry의 BatchSpanProcessor를 상속한 LangfuseSpanProcessor를 사용합니다.

# langfuse/_client/span_processor.py
from opentelemetry.sdk.trace.export import BatchSpanProcessor

class LangfuseSpanProcessor(BatchSpanProcessor):
    """Langfuse 전용 필터링 및 인증을 추가한 BatchSpanProcessor 확장"""
    ...

BatchSpanProcessor는 내부적으로 Python 표준 threading과 collections.deque를 사용합니다.

백그라운드 스레드는 두 가지 역할로 분리되어 있습니다.

span/trace 전송: LangfuseSpanProcessor (OTel BatchSpanProcessor 상속)
score ingestion, 미디어 업로드: LangfuseResourceManager의 별도 consumer 스레드 (threading 직접 사용)

참고: langfuse-python GitHub — span_processor.py

Langfuse SDK v2 (레거시)

v2는 구조가 완전히 다릅니다. OTel 기반이 아니라 자체 TaskManager가 threading으로 consumer 스레드를 직접 생성합니다.

# langfuse/task_manager.py (v2)
def init_resources(self):
    for i in range(self._threads):
        ingestion_consumer = IngestionConsumer(...)
        ingestion_consumer.start()  # threading.Thread.start() 직접 호출

이 구조 때문에 Gunicorn --preload 환경에서 fork-unsafe 문제가 발생합니다. (자세한 내용은 5번 섹션 참고)

OpenTelemetry BatchSpanProcessor

BatchSpanProcessor 자체는 얇은 래퍼이고, 실제 로직은 공통 클래스인 BatchProcessor에 위임됩니다. deque, 워커 스레드, 트리거 조건 모두 이 공통 클래스 안에 구현되어 있습니다.

opentelemetry-sdk/src/opentelemetry/sdk/
ㄴ trace/export/__init__.py         ← BatchSpanProcessor (래퍼)
ㄴ _shared_internal/__init__.py     ← BatchProcessor (실제 로직: deque, 워커 스레드)

참고: OpenTelemetry Python SDK 소스코드 — _shared_internal/__init__.py

4. 싱글톤 패턴과 스레드 초기화 시점

Langfuse SDK

Langfuse SDK는 싱글톤 패턴을 사용합니다. public_key를 키로 하는 싱글톤으로 관리되며, 백그라운드 스레드는 Langfuse() 클라이언트가 처음 초기화될 때 한 번 생성됩니다.

# 이 시점에 백그라운드 스레드 생성
langfuse = Langfuse(public_key="pk-lf-...", secret_key="sk-lf-...")

# 동일한 public_key로 재호출 시 기존 싱글톤 재사용, 스레드 새로 안 만듦
langfuse2 = Langfuse(public_key="pk-lf-...")  # 기존 인스턴스 반환

명시적으로 Langfuse()를 호출하지 않아도 get_client()를 처음 호출할 때 환경변수 기반으로 자동 초기화됩니다.

참고: Langfuse Python SDK Overview

Phoenix (OpenTelemetry TracerProvider)

Phoenix는 Langfuse처럼 자체 싱글톤 패턴을 구현하지 않습니다. 대신 OpenTelemetry의 전역 TracerProvider 메커니즘을 사용합니다.

register()를 호출하면 TracerProvider가 생성되고, 기본적으로 OpenTelemetry 전역 provider로 등록됩니다.

from phoenix.otel import register

# TracerProvider 생성 + 전역 등록 + BatchSpanProcessor 워커 스레드 시작
tracer_provider = register(
    project_name="my-app",
    batch=True,
    set_global_tracer_provider=True,  # 기본값 True
)

전역 TracerProvider는 한 번만 설정 가능합니다. 이후 set_tracer_provider()를 다시 호출하면 경고 로그가 남고 무시됩니다. 따라서 register()는 앱 시작 시점에 한 번만 호출해야 합니다.

BatchSpanProcessor의 워커 스레드는 TracerProvider가 생성될 때 함께 시작됩니다. 종료 시에는 tracer_provider.shutdown()을 명시적으로 호출해야 워커 스레드가 정상 종료되고, 큐에 남은 span이 flush됩니다.

# FastAPI lifespan에서 Phoenix(OTel) 종료 처리
from contextlib import asynccontextmanager
from fastapi import FastAPI
from opentelemetry import trace

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    # 종료 시 미전송 span flush 후 워커 스레드 종료
    trace.get_tracer_provider().shutdown()

app = FastAPI(lifespan=lifespan)

참고: Phoenix OTEL register() 공식 문서

5. Gunicorn / Uvicorn 멀티 프로세스 환경에서의 주의사항

Gunicorn pre-fork 모델

Gunicorn은 pre-fork 모델을 사용합니다. HTTP 요청을 받기 전에 마스터 프로세스가 워커를 미리 os.fork()로 생성합니다.

“The pre in pre-forked means that the master process creates the workers before handling any HTTP request.”

— Gunicorn 아키텍처 설명

os.fork()는 부모 프로세스의 메모리는 복사하지만 스레드는 복사하지 않습니다. POSIX 표준에 따른 동작입니다.

Gunicorn `--preload` 옵션

--preload는 메모리 절약을 위한 옵션입니다.

기본적으로 Gunicorn은 fork 후 각 워커가 앱 코드를 개별적으로 로드합니다. --preload를 사용하면 마스터 프로세스에서 앱을 먼저 로드한 뒤 fork하여, OS의 copy-on-write 덕분에 워커들이 메모리 페이지를 공유할 수 있습니다.

“By preloading an application you can save some RAM resources as well as speed up server boot times.”

— Gunicorn 공식 문서

	기본 (no preload)	`--preload`
앱 로드 시점	fork 후 각 워커가 개별 로드	fork 전 마스터에서 한 번 로드
메모리	워커 수 × 앱 크기	copy-on-write로 공유 → 절약
부팅 속도	느림	빠름
`--reload`와 호환	가능	불가

SDK 버전별 fork 안전성

SDK	버전	span 전송 방식	`os.register_at_fork`	`--preload` 안전성
Langfuse	v2	`TaskManager` 자체 `threading`	없음	위험
Langfuse	v3/v4	`BatchSpanProcessor` 상속 (`LangfuseSpanProcessor`)	상속받음	안전
Phoenix (OTel)	-	`BatchSpanProcessor`	있음	안전

Langfuse v2의 문제

v2는 TaskManager.__init__에서 바로 consumer 스레드를 시작합니다. --preload 환경에서 전역으로 Langfuse()를 초기화하면 마스터 프로세스에서 스레드가 생성된 뒤 fork가 일어나고, 자식 프로세스에는 스레드가 없어서 이벤트가 전송되지 않습니다. 최악의 경우 RuntimeError: can't start new thread가 발생합니다.

실제 사례: Langfuse GitHub Issue #3405

# X v2, --preload 환경에서 위험
langfuse = Langfuse()  # 마스터에서 초기화 → fork 후 워커에 스레드 없음

# O v2, --preload 환경에서 안전: post_fork 훅 활용
# gunicorn.conf.py
def post_fork(server, worker):
    import app as application
    application.langfuse = None         # 마스터에서 생성된 인스턴스 초기화
    application.langfuse = Langfuse()   # fork 이후 워커에서 새로 초기화

v2는 현재 유지보수가 종료된 레거시 버전입니다. 근본적인 해결은 v3/v4로 업그레이드입니다.

Langfuse v3/v4와 Phoenix는 안전한 이유

BatchSpanProcessor는 내부적으로 os.register_at_fork를 사용해 fork 후 자식 프로세스에서 워커 스레드를 자동으로 재초기화합니다.

# opentelemetry-sdk 내부 (_shared_internal/__init__.py)
if hasattr(os, "register_at_fork"):
    weak_reinit = weakref.WeakMethod(self._at_fork_reinit)
    os.register_at_fork(after_in_child=lambda: weak_reinit()())

Langfuse v3/v4의 LangfuseSpanProcessor는 BatchSpanProcessor를 상속하므로 이 보호가 자동으로 적용됩니다.

Uvicorn `--workers`

Uvicorn은 --workers 옵션으로 멀티 프로세스를 띄울 때 Gunicorn과 달리 os.fork()가 아닌 Python multiprocessing 라이브러리의 spawn 방식을 사용합니다. spawn은 완전히 새로운 Python 인터프리터를 시작하므로 앱 코드를 처음부터 다시 실행합니다. 따라서 모든 버전의 Langfuse SDK와 Phoenix가 각 워커에서 새로 초기화되어 fork 문제가 발생하지 않습니다.

uvicorn main:app --workers 4
    ↓ spawn → 새 Python 인터프리터 × 4
    ↓ 각 워커에서 앱 코드 처음부터 실행
    ↓ SDK 각자 초기화 → 정상

배포 환경별 정리

환경	멀티 프로세스 방식	Langfuse v2	Langfuse v3/v4	Phoenix
`uvicorn --workers N`	spawn	안전	안전	안전
`gunicorn` (기본)	os.fork (앱은 워커에서 로드)	안전	안전	안전
`gunicorn --preload`	os.fork (앱을 마스터에서 로드)	위험	안전	안전

6. FastAPI + Langfuse / Phoenix 권장 설정

Langfuse (v3/v4)

from contextlib import asynccontextmanager
from fastapi import FastAPI
from langfuse import get_client

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    # 종료 시 미전송 이벤트 모두 flush 후 스레드 종료
    get_client().shutdown()

app = FastAPI(lifespan=lifespan)

shutdown() 없이 프로세스가 종료되면 큐에 남은 이벤트가 유실될 수 있습니다.

참고: Langfuse Python SDK 공식 문서

Langfuse v2 + Gunicorn `--preload`

# gunicorn.conf.py
preload_app = True

def post_fork(server, worker):
    import app as application
    application.langfuse = None
    application.langfuse = application.get_langfuse()

def worker_exit(server, worker):
    import app as application
    if application.langfuse is not None:
        application.langfuse.flush()

Phoenix

from contextlib import asynccontextmanager
from fastapi import FastAPI
from phoenix.otel import register
from opentelemetry import trace

tracer_provider = register(
    project_name="my-app",
    batch=True,  # 프로덕션에서 반드시 명시
)

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    # 종료 시 미전송 span flush 후 워커 스레드 종료
    trace.get_tracer_provider().shutdown()

app = FastAPI(lifespan=lifespan)

tracer_provider.shutdown()을 호출하지 않으면 BatchSpanProcessor 워커 스레드가 살아 있는 상태로 프로세스가 종료되어 큐에 남은 span이 유실될 수 있습니다.

참고 문서

폐쇄망 Docker Network Subnet 충돌로 인해 특정 서버 SSH/Ping Timeout 발생한 장애 분석

2026-05-12T00:00:00+09:00

개발서버에서 Docker compose를 이용해 container를 띄운 후 부터, 갑자기 Local → 개발서버로의 모든 SSH/PING/HTTP 요청에 대해 Timeout이 발생했다.
처음에는 방화벽 문제라고 생각했지만, 실제 원인은 Docker Network Subnet 충돌로 인해 호스트 라우팅 테이블이 꼬인 문제였다.

이번 글에서는 다음 순서로 정리한다.

문제 상황
문제 원인
원인 분석 과정
해결 방법
재발 방지 방법

문제 상황

운영 중인 서버에서 갑자기 다음과 같은 현상이 발생했다.

증상

Docker compose 컨테이너를 띄운 서버만 SSH timeout 발생
ping timeout 발생
다른 서버들은 정상 접속 가능
다른 서버 → 문제 서버 SSH, HTTP 가능
로컬 PC → 문제 서버만 접속 불가
Docker 컨테이너 포트는 LISTEN 상태
sshd 프로세스 정상 동작

예시:

ssh user@server -p 7002

결과:

Connection timed out

ping도 동일하게 timeout 발생:

ping server-ip

처음 의심했던 원인들

처음에는 아래 항목들을 의심했다.

운영 방화벽 whitelist 누락
fail2ban 차단
sshd 장애
Docker iptables 충돌
Security Group 문제
서버 네트워크 장애

하지만 이상한 점이 있었다.

이상했던 점

다른 서버에서는 문제 서버로 SSH 및 HTTP 요청이 정상 동작했다.

즉

다른 서버 -> 문제 서버 : 정상
내 PC -> 문제 서버 : timeout

이 상태였다.

즉 서버 자체는 살아있고, 특정 source network에서만 문제가 발생하는 상황이었다.

원인 분석

문제 서버에서 Docker Network 목록을 확인했다.

docker network ls

이후 특정 네트워크의 subnet을 확인했다.

docker network inspect 네트워크명

그리고 문제를 발견했다.

문제의 Docker Subnet

Docker Network가 다음과 같은 subnet을 사용 중이었다.

aaa.bbb.0.0/16

그런데 내 로컬 PC IP도 동일한 대역이었다.

예:

aaa.bbb.x.x

실제로 발생한 문제

Docker는 Network를 생성할 때 호스트 OS의 라우팅 테이블에 route를 추가한다.

호스트 라우팅 테이블 확인

ip route

문제 상황에서는 이런 route가 추가되어 있었다.

aaa.bbb.0.0/16 dev br-xxxxx

의미:

aaa.bbb.* 대역은 Docker Bridge Network로 보내라

즉 서버는 내 PC IP를 외부 네트워크가 아니라 Docker 내부 네트워크 주소로 오인하게 되었다.

왜 timeout이 발생했는가?

패킷 흐름은 다음과 같았다.

내 PC -> 서버

패킷은 정상적으로 서버까지 도착한다.

서버 -> 내 PC 응답

문제는 여기서 발생한다.

서버는

aaa.bbb.0.x 는 Docker Network 대역

이라고 판단하여 응답 패킷을 실제 NIC(eth0)가 아니라 Docker Bridge(br-xxxx)로 보내버렸다.

즉 응답 패킷이 잘못된 인터페이스로 라우팅되면서

ping timeout
ssh timeout
http timeout

이 발생한 것이다.

확인 방법

현재 라우팅 테이블 확인

ip route

특정 IP가 어디로 라우팅되는지 확인

ip route get 내PC_IP

문제 상황에서는

aaa.bbb.0.106 dev br-xxxxx

처럼 Docker Bridge로 라우팅되고 있었다.

해결 방법

문제가 되는 Docker Network를 삭제했다.

docker network rm 네트워크명

삭제 직후 모든 문제가 즉시 해결되었다.

ping 정상화
SSH 정상화
HTTP 정상화

재발 방지 방법

가장 중요한 건 Docker Network 대역을 명시적으로 관리하는 것이다.

특히 폐쇄망/사내망 환경에서는 반드시 필요하다.

방법 1. Docker Default Address Pool 고정

/etc/docker/daemon.json

{
  "default-address-pools": [
    {
      "base": "172.30.0.0/16",
      "size": 24
    }
  ]
}

적용 후 아래 명령어 실행

sudo systemctl restart docker

방법 2. Docker Compose에서 Subnet 명시

networks:
  backend:
    ipam:
      config:
        - subnet: aaa.bbb.10.0/24

운영 환경에서 주의할 점

사내망/VPN 환경에서는 아래 대역이 이미 사용 중인 경우가 많다.

x.x.x
168.x.x
16.x.x ~ 172.31.x.x

Docker 자동 subnet 할당을 그대로 사용하면 실제 네트워크와 충돌할 수 있다.

결론

이번 장애의 핵심 원인은

Docker Network Subnet이 실제 네트워크 대역과 충돌하면서 호스트 라우팅 테이블이 Docker Bridge를 우선하게 된 것

이었다.

Docker Network는 단순히 컨테이너 내부만 사용하는 것이 아니라, 호스트 OS의 라우팅에도 직접 영향을 준다.

특히 폐쇄망/사내망 환경에서는 반드시 Docker Subnet 정책을 명시적으로 관리해야 한다.

TIL

FastAPI + LangGraph AI Agent self-hosted 모니터링 플랫폼 비교(Langfuse vs Arize Phoenix)

1. Langfuse vs Arize Phoenix 선택 기준

LangGraph 연동 방식

기능 비교

2. 기본 개념 정리

Trace와 Span

Ingestion

3. Langfuse Self-hosted 아키텍처

구성 요소

각 구성 요소의 역할

데이터 흐름

langfuse-web vs langfuse-worker 분리 이유

S3 / MinIO 사용 목적

S3 데이터 삭제 정책

Redis 역할 상세

4. Arize Phoenix Self-hosted 아키텍처

구성 요소

데이터 흐름

스토리지

5. 구조 비교 요약

6. 결론

참고

Langfuse & Phoenix SDK 동작 원리 및 FastAPI 성능 영향 & 배포시 주의사항

1. SDK는 FastAPI에 부하를 주는가?

Langfuse Python SDK

Phoenix (OpenTelemetry BatchSpanProcessor)

2. GIL과 백그라운드 스레드

3. 백그라운드 스레드 구현

Langfuse SDK (v3/v4)

Langfuse SDK v2 (레거시)

OpenTelemetry BatchSpanProcessor

4. 싱글톤 패턴과 스레드 초기화 시점

Langfuse SDK

Phoenix (OpenTelemetry TracerProvider)

5. Gunicorn / Uvicorn 멀티 프로세스 환경에서의 주의사항

Gunicorn pre-fork 모델

Gunicorn --preload 옵션

SDK 버전별 fork 안전성

Langfuse v2의 문제

Langfuse v3/v4와 Phoenix는 안전한 이유

Uvicorn --workers

배포 환경별 정리

6. FastAPI + Langfuse / Phoenix 권장 설정

Langfuse (v3/v4)

Langfuse v2 + Gunicorn --preload

Phoenix

참고 문서

폐쇄망 Docker Network Subnet 충돌로 인해 특정 서버 SSH/Ping Timeout 발생한 장애 분석

문제 상황

증상

처음 의심했던 원인들

이상했던 점

원인 분석

문제의 Docker Subnet

실제로 발생한 문제

왜 timeout이 발생했는가?

확인 방법

현재 라우팅 테이블 확인

특정 IP가 어디로 라우팅되는지 확인

해결 방법

재발 방지 방법

방법 1. Docker Default Address Pool 고정

방법 2. Docker Compose에서 Subnet 명시

운영 환경에서 주의할 점

결론

Gunicorn `--preload` 옵션

Uvicorn `--workers`

Langfuse v2 + Gunicorn `--preload`