Grafana-Alloy on ICE-ICE-BEAR-BLOG

FastAPI 애플리케이션에 Grafana Cloud 옵저버빌리티 구축하기

Mon, 06 Apr 2026 00:00:00 +0900

개요

hybrid-image-search FastAPI 서비스에 OpenTelemetry 기반 분산 추적을 붙였다. 목표는 단순했다 — 이미지 검색 요청이 들어왔을 때 벡터 검색부터 Gemini API 호출까지 어디서 시간이 소요되는지 한눈에 보는 것. 그런데 패키지 설치부터 Grafana에서 트레이스가 실제로 보이기까지 12번의 수정이 필요했다. 이 글에서는 전체 아키텍처, 실제 코드, 그리고 삽질 과정을 정리한다.

아키텍처

옵저버빌리티 파이프라인은 세 계층으로 구성된다. FastAPI 앱이 OpenTelemetry로 트레이스를 생성하고, 같은 EC2 인스턴스의 Grafana Alloy가 수집/배치 처리하며, Grafana Cloud Tempo에 저장된 트레이스를 UI에서 조회한다.

flowchart LR
 A["FastAPI App <br/> OpenTelemetry SDK"] -->|OTLP HTTP :4318| B["Grafana Alloy <br/> on EC2"]
 B -->|OTLP HTTP| C["Grafana Cloud <br/> Tempo"]
 C --> D["Grafana UI <br/> Trace Explorer"]

핵심 설계 포인트는 gRPC가 아닌 OTLP HTTP (포트 4318)를 사용한 것이다. 이 선택이 왜 중요했는지는 디버깅 섹션에서 다룬다.

1단계: 텔레메트리 모듈

설정의 핵심은 import 시점에 OpenTelemetry를 초기화하는 telemetry.py 모듈이다:

# backend/src/telemetry.py
import logging, os
from contextlib import contextmanager
import psutil
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

_endpoint = os.environ.get(
 "OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318"
)
_environment = os.environ.get("DEPLOYMENT_ENV", "dev")

_resource = Resource.create({
 "service.name": "hybrid-image-search",
 "deployment.environment": _environment,
})

_provider = TracerProvider(resource=_resource)
_exporter = OTLPSpanExporter(endpoint=f"{_endpoint}/v1/traces")
_provider.add_span_processor(SimpleSpanProcessor(_exporter))
trace.set_tracer_provider(_provider)

tracer = trace.get_tracer("hybrid-image-search")

세 가지 포인트:

TracerProvider를 모듈 레벨에서 설정한다. 함수 안에서 하면 안 된다. FastAPIInstrumentor가 import 시점에 tracer provider 참조를 캐시하기 때문에, lifespan 함수에서 나중에 설정하면 이미 no-op provider를 잡고 있다.
SimpleSpanProcessor를 사용한다. BatchSpanProcessor는 백그라운드 스레드에서 배치 전송하므로 성능은 좋지만, uv run으로 실행할 때 프로세스가 flush 전에 종료될 수 있다. SimpleSpanProcessor는 동기 전송이라 유실이 없다.
OTLP HTTP exporter를 사용한다. gRPC는 grpcio 의존성이 필요하고 이 환경에서 안정성 문제가 있었다. HTTP exporter는 requests 기반이라 그냥 동작한다.

2단계: traced_span 헬퍼

자동 계측 외에, 각 스팬별 리소스 사용량 — Gemini API 호출의 메모리 할당량, 벡터 검색의 CPU 시간 — 도 보고 싶었다:

_process = psutil.Process(os.getpid())

@contextmanager
def traced_span(name, **attrs):
 """CPU/메모리 측정이 포함된 스팬 생성."""
 mem_before = _process.memory_info().rss
 cpu_before = _process.cpu_times()
 with tracer.start_as_current_span(name) as span:
 for k, v in attrs.items():
 span.set_attribute(k, v)
 yield span
 mem_after = _process.memory_info().rss
 cpu_after = _process.cpu_times()
 span.set_attribute("process.memory_mb",
 round(mem_after / 1024 / 1024, 1))
 span.set_attribute("process.memory_delta_kb",
 round((mem_after - mem_before) / 1024, 1))
 span.set_attribute("process.cpu_user_ms",
 round((cpu_after.user - cpu_before.user) * 1000, 1))
 span.set_attribute("process.cpu_system_ms",
 round((cpu_after.system - cpu_before.system) * 1000, 1))

generation 라우트에서의 사용 예:

with traced_span("generation.gemini_api", model=model_name):
 response = await model.generate_content_async(prompt)

with traced_span("generation.prompt_build", ref_count=len(references)):
 prompt = build_prompt(query, references)

Grafana Tempo에서 이들은 FastAPI 루트 스팬의 하위 스팬으로 표시되며, 스팬 상세 패널에서 메모리/CPU 속성을 확인할 수 있다.

3단계: FastAPI 연결

애플리케이션 연결은 두 곳에서 이루어진다:

# main.py — 모듈 레벨 (app 생성 후)
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
FastAPIInstrumentor.instrument_app(app)

# main.py — lifespan 함수
from telemetry import init_telemetry

@asynccontextmanager
async def lifespan(app):
 try:
 init_telemetry(db_engine=db_engine)
 except Exception as e:
 logger.warning("Telemetry init failed: %s", e)
 yield

init_telemetry는 SQLAlchemy 계측 같은 선택적 기능을 처리한다. 핵심은 FastAPIInstrumentor를 모듈 레벨에 두는 것이다. lifespan 안에서 계측하면 잘못된 tracer provider를 캡처할 수 있다.

텔레메트리 초기화의 try/except는 의도적이다 — 관측성 때문에 앱이 죽으면 안 된다. Alloy가 내려가 있거나 엔드포인트 설정이 잘못되어도 서비스는 정상 동작해야 한다.

4단계: EC2의 Grafana Alloy

Grafana Alloy는 로컬 컬렉터 역할을 한다. FastAPI 앱으로부터 OTLP 트레이스를 받아 배치 처리 후 Grafana Cloud로 전달한다:

otelcol.receiver.otlp "default" {
 grpc { endpoint = "127.0.0.1:4317" }
 http { endpoint = "127.0.0.1:4318" }
 output {
 traces = [otelcol.processor.batch.default.input]
 }
}

otelcol.processor.batch "default" {
 timeout = "5s"
 output {
 traces = [otelcol.exporter.otlphttp.grafana_cloud.input]
 }
}

otelcol.exporter.otlphttp "grafana_cloud" {
 client {
 endpoint = env("GRAFANA_OTLP_ENDPOINT")
 auth = otelcol.auth.basic.grafana_cloud.handler
 }
}

otelcol.auth.basic "grafana_cloud" {
 username = env("GRAFANA_INSTANCE_ID")
 password = env("GRAFANA_API_TOKEN")
}

Alloy는 127.0.0.1에만 바인딩되어 외부 노출이 없다. 인증 정보는 환경 변수로 주입하며, EC2의 systemd unit 파일에서 설정한다.

5초 배치 타임아웃은 적절한 균형점이다 — 실시간에 가까운 가시성을 제공하면서도 요청당 여러 스팬을 묶을 수 있다.

디버깅 여정

패키지 설치부터 Grafana에서 트레이스가 보이기까지 약 12번의 수정이 필요했다. 주요 이슈와 해결 과정은 다음과 같다:

단계	문제	해결
1	트레이스가 전혀 안 보임	TracerProvider를 lifespan에서 설정했는데, FastAPIInstrumentor가 이미 no-op provider를 캐시한 상태. 모듈 레벨로 이동.
2	프로세스 종료 시 트레이스 유실	`BatchSpanProcessor`의 백그라운드 스레드가 `uv run` 종료 전에 flush 못 함. `SimpleSpanProcessor`로 전환.
3	gRPC 연결 실패	EC2에서 `grpcio`의 간헐적 문제. OTLP HTTP exporter로 전환.
4	Alloy 다운 시 앱 크래시	`init_telemetry` 주위에 에러 핸들링 없었음. lifespan에 try/except 추가.
5	FastAPI 스팬에 커스텀 속성 누락	tracer provider 설정 전에 `FastAPIInstrumentor` 호출. provider를 import 시점에, instrumentor를 `app` 생성 후 모듈 레벨에서 호출하도록 수정.

가장 미묘한 버그는 1번이었다. OpenTelemetry의 글로벌 tracer provider는 싱글턴이다 — FastAPIInstrumentor가 한 번 읽으면 그 참조를 캐시한다. 그 시점에 글로벌 provider가 아직 no-op 기본값이면, 나중에 진짜 provider를 설정해도 자동 계측된 스팬은 전부 허공으로 사라진다.

Grafana에서 보이는 것

모든 설정이 완료되면, Grafana Tempo에서 service.name = hybrid-image-search로 필터링하면 전체 요청 워터폴을 볼 수 있다:

flowchart TD
 A["GET /search"] --> B["search.vector_query"]
 A --> C["search.rerank"]
 A --> D["generation.injection"]
 D --> E["generation.prompt_build"]
 E --> F["generation.gemini_api"]

각 스팬에는 다음 정보가 포함된다:

Duration — 소요 시간
process.memory_mb — 스팬 종료 시점의 RSS
process.memory_delta_kb — 스팬 실행 중 할당된 메모리
process.cpu_user_ms / process.cpu_system_ms — 소비된 CPU 시간

예를 들어 generation.gemini_api 스팬은 평균 1.2초에 ~8MB를 할당하고, search.vector_query는 200ms에 메모리 영향이 거의 없다는 것을 바로 확인할 수 있다.

배운 점

TracerProvider는 import 시점에 설정하라. import나 모듈 레벨에서 실행되는 instrumentor는 그 시점의 provider를 캡처한다. 늦은 초기화는 조용한 no-op을 의미한다.
개발 환경과 단기 프로세스에서는 SimpleSpanProcessor를 쓰라. BatchSpanProcessor가 프로덕션 처리량에는 유리하지만, 클린 셧다운에 의존한다. 프로세스가 갑자기 종료되면 스팬이 유실된다.
OTLP HTTP가 gRPC보다 이식성이 좋다. 의존성이 적고, 디버깅이 쉽고 (curl로 엔드포인트 테스트 가능), protobuf 컴파일 문제도 없다.
Alloy를 로컬 컬렉터로 두는 것이 클라우드 직접 전송보다 낫다. 앱과 Grafana Cloud 인증을 분리하고, 배치 처리와 재시도를 처리하며, 앱은 localhost:4318만 알면 된다.
텔레메트리 초기화에 에러 핸들링을 넣어라. 관측성은 graceful하게 열화되어야 한다. 컬렉터 설정 오류가 애플리케이션을 죽여서는 안 된다.
psutil을 활용한 커스텀 리소스 메트릭은 비용 대비 가치가 높다. 스팬당 memory_info()와 cpu_times() 호출의 오버헤드는 무시할 수준이지만, 타이밍 데이터와 함께 메모리/CPU 정보가 있으면 성능 디버깅이 훨씬 풍부해진다.

Hybrid Image Search 개발기 #9 — OpenTelemetry 분산 추적, Grafana Cloud 연동, traced_span 헬퍼

Mon, 06 Apr 2026 00:00:00 +0900

개요

이전 글: Hybrid Image Search 개발기 #8에서 톤/앵글 S3 마이그레이션과 EC2 배포 수정, hex 컬러 추출을 다뤘다. 이번에는 한 발짝 물러서서 관측 가능성(observability)에 집중했다.

FastAPI 서버에 OpenTelemetry를 도입해 검색 파이프라인과 이미지 생성 파이프라인의 각 단계를 스팬으로 추적하고, EC2에 Grafana Alloy를 설치해 트레이스를 Grafana Cloud로 전송하는 구성을 완성했다. 이틀에 걸친 작업이었는데, 1일차의 깔끔한 구현과 2일차의 현실적인 디버깅이 극명하게 대비되었다.

아키텍처 — 트레이스 수집 경로

아래 다이어그램은 트레이스가 앱에서 Grafana Cloud까지 전달되는 경로를 보여준다.

flowchart LR
 A["FastAPI 앱 <br/> (OTel SDK)"] -->|OTLP HTTP| B["Grafana Alloy <br/> (localhost:4318)"]
 B -->|OTLP HTTP| C["Grafana Cloud <br/> Tempo"]
 C --> D["Grafana UI <br/> 트레이스 조회"]
 A -->|스팬 생성| E["traced_span <br/> CPU/메모리 메트릭"]
 E --> A

핵심 구성요소는 세 가지다. 앱 내부의 OTel SDK가 스팬을 생성하고, EC2 로컬의 Grafana Alloy가 OTLP 수신 후 배치 처리하며, Grafana Cloud Tempo가 최종 저장 및 조회를 담당한다.

1일차 — 깔끔한 초기 구현

첫날은 순조로웠다. OpenTelemetry 패키지를 추가하고, 텔레메트리 모듈을 만들고, 앱 라이프사이클에 연결하고, 두 파이프라인에 스팬을 삽입했다.

텔레메트리 모듈 구조

# telemetry.py — Provider를 임포트 시점에 설정
_resource = Resource.create({
 "service.name": "hybrid-image-search",
 "deployment.environment": _environment,
})
_provider = TracerProvider(resource=_resource)
_exporter = OTLPSpanExporter(endpoint=f"{_endpoint}/v1/traces")
_provider.add_span_processor(SimpleSpanProcessor(_exporter))
trace.set_tracer_provider(_provider)
tracer = trace.get_tracer("hybrid-image-search")

TracerProvider를 모듈 수준에서 설정하는 이유는, uvicorn이 ASGI 앱을 바인딩하기 전에 provider가 준비되어야 FastAPIInstrumentor가 올바른 provider를 참조하기 때문이다.

파이프라인 스팬 삽입

검색 파이프라인에는 임베딩 생성, 벡터 검색, 재랭킹 등 단계별로 스팬을 삽입했다. 생성 파이프라인에는 레퍼런스 주입(generation.injection), 프롬프트 빌드(generation.prompt_build), Gemini API 호출(generation.gemini_api) 스팬을 추가했다.

DB 인덱스도 함께 추가했다. 검색과 생성 쿼리 성능이 트레이스에서 병목으로 보이기 전에 미리 정리한 것이다.

2일차 — 현실과의 충돌

EC2에 Grafana Alloy를 설치하고 Grafana Cloud 연동을 설정한 후, 트레이스가 전혀 나타나지 않았다. 여기서부터 연속 6개의 fix 커밋이 이어졌다.

문제 1: TracerProvider 초기화 시점

uvicorn이 앱을 로드하는 시점에 TracerProvider가 아직 설정되지 않아 FastAPIInstrumentor가 기본(no-op) provider를 참조했다. 해결: 모듈 임포트 시점에 provider를 설정하도록 변경.

문제 2: BatchSpanProcessor의 비동기 플러시

uv run으로 실행하면 프로세스가 빠르게 종료되면서 BatchSpanProcessor의 백그라운드 스레드가 스팬을 내보내기 전에 죽었다. 해결: SimpleSpanProcessor로 교체해 스팬 생성 즉시 동기적으로 전송.

문제 3: gRPC exporter 침묵

gRPC exporter가 연결 실패를 로그 없이 삼키고 있었다. 해결: OTLP HTTP exporter로 전환. HTTP는 디버깅이 용이하고 Alloy의 기본 HTTP 엔드포인트(4318)와 바로 호환된다.

문제 4: 텔레메트리 초기화 크래시

OTel 초기화 중 예외가 발생하면 앱 전체가 죽었다. 해결: try/except로 감싸서 텔레메트리 실패가 앱 가동을 막지 않도록 변경.

문제 5: FastAPIInstrumentor provider 누락

FastAPIInstrumentor().instrument()가 글로벌 provider를 자동으로 찾지 못하는 경우가 있었다. 해결: tracer_provider를 명시적으로 전달.

문제 6: 모듈 임포트 순서

main.py에서 app = FastAPI()와 instrumentation 호출의 순서 문제. 해결: FastAPIInstrumentor를 모듈 수준에서 app 생성 직후에 호출.

Grafana Alloy 구성

EC2에 배포한 Alloy 설정은 간결하다.

otelcol.receiver.otlp "default" {
 grpc { endpoint = "127.0.0.1:4317" }
 http { endpoint = "127.0.0.1:4318" }
 output { traces = [otelcol.processor.batch.default.input] }
}
otelcol.processor.batch "default" {
 timeout = "5s"
 output { traces = [otelcol.exporter.otlphttp.grafana_cloud.input] }
}
otelcol.exporter.otlphttp "grafana_cloud" {
 client {
 endpoint = env("GRAFANA_OTLP_ENDPOINT")
 auth = otelcol.auth.basic.grafana_cloud.handler
 }
}
otelcol.auth.basic "grafana_cloud" {
 username = env("GRAFANA_INSTANCE_ID")
 password = env("GRAFANA_API_TOKEN")
}

앱은 localhost:4318로 OTLP HTTP를 보내고, Alloy가 5초 배치로 묶어 Grafana Cloud Tempo로 전송한다. 인증 정보는 환경 변수로 관리한다.

traced_span — CPU/메모리 메트릭 자동 수집

마지막으로 traced_span 컨텍스트 매니저를 만들어, 스팬 전후의 CPU 시간과 메모리 사용량을 자동으로 측정해 스팬 속성에 기록하도록 했다.

@contextmanager
def traced_span(name, **attrs):
 """CPU/메모리 측정이 포함된 스팬 생성."""
 mem_before = _process.memory_info().rss
 cpu_before = _process.cpu_times()
 with tracer.start_as_current_span(name) as span:
 for k, v in attrs.items():
 span.set_attribute(k, v)
 yield span
 mem_after = _process.memory_info().rss
 cpu_after = _process.cpu_times()
 span.set_attribute("process.memory_mb",
 round(mem_after / 1024 / 1024, 1))
 span.set_attribute("process.memory_delta_kb",
 round((mem_after - mem_before) / 1024, 1))
 span.set_attribute("process.cpu_user_ms",
 round((cpu_after.user - cpu_before.user) * 1000, 1))
 span.set_attribute("process.cpu_system_ms",
 round((cpu_after.system - cpu_before.system) * 1000, 1))

psutil.Process로 현재 프로세스의 RSS 메모리와 CPU user/system 시간을 스팬 시작/종료 시점에 측정한다. 이를 통해 Grafana에서 각 파이프라인 단계가 소비하는 리소스를 개별적으로 확인할 수 있다. 검색 파이프라인과 생성 파이프라인 모두 traced_span으로 교체 완료했다.

커밋 로그

메시지	변경 파일
feat: add no-text directive for injected refs and remove color palettes	`prompt.py`, `App.tsx`, `GeneratedImageDetail.tsx`
deps: add OpenTelemetry packages for observability	`requirements.txt`
feat: add telemetry module with OpenTelemetry init and tracer	`telemetry.py`
feat: wire OpenTelemetry init into app lifespan	`main.py`
feat: add OpenTelemetry spans to search pipeline stages	`search.py`
feat: add OpenTelemetry spans to generation pipeline	`generation.py`
add indices	DB migration
infra: add Grafana Alloy config and EC2 setup guide	`infra/alloy/config.alloy`
deps: move OpenTelemetry packages to pyproject.toml	`pyproject.toml`
fix: set OTel TracerProvider at import time	`telemetry.py`
fix: use SimpleSpanProcessor for reliable export under uv run	`telemetry.py`
fix: switch to OTLP HTTP exporter for reliable trace delivery	`telemetry.py`
fix: add error handling for telemetry init	`telemetry.py`
fix: pass tracer_provider explicitly to FastAPIInstrumentor	`main.py`
fix: move FastAPI instrumentation to module level in main.py	`main.py`
feat: add traced_span helper with CPU/memory resource metrics	`telemetry.py`
feat: use traced_span for CPU/memory metrics in search and generation pipelines	`search.py`, `generation.py`

인사이트

OTel 초기화는 반드시 임포트 시점에 완료하라. uvicorn 같은 ASGI 서버는 앱 모듈을 임포트한 직후 라우터와 미들웨어를 바인딩한다. FastAPIInstrumentor가 이 시점에 유효한 TracerProvider를 찾지 못하면 no-op tracer를 캐시해 버리고, 이후 아무리 provider를 설정해도 계측이 동작하지 않는다. 모듈 최상단에서 provider를 설정하는 패턴이 이 문제를 근본적으로 방지한다.

BatchSpanProcessor는 장수(long-lived) 프로세스 전용이다. uv run이나 테스트처럼 프로세스가 빠르게 종료되는 환경에서는 백그라운드 플러시 스레드가 작동할 틈이 없다. SimpleSpanProcessor는 성능 대비 안정성 트레이드오프가 명확하지만, 개발/소규모 프로덕션에서는 합리적인 선택이다.

gRPC보다 HTTP를 먼저 시도하라. OTLP gRPC exporter는 연결 실패를 조용히 처리해 디버깅을 어렵게 만든다. HTTP exporter는 상태 코드와 에러 메시지를 명확히 반환하므로, 새 인프라를 연결할 때 HTTP로 먼저 동작을 확인한 뒤 필요시 gRPC로 전환하는 것이 효율적이다.