ADR-003 OTel Collector 단일 게이트웨이 배치

• 상태: 채택
• 날짜: 2026-07-03
• 근거: PRD FR-3 / TDD “시스템 역할 경계”

맥락

trace·log를 백엔드(Tempo·Loki)로 보낼 때, 앱이 Tempo/Loki에 직접 붙을지 Collector를 경유할지 결정이 필요하다. Grafana docker-otel-lgtm은 Collector를 게이트웨이로 두는 토폴로지를 제공한다.

결정

단일 OTel Collector를 게이트웨이로 배치한다. 앱은 OTLP HTTP(otel-collector:4318, trace는 /v1/traces) 한 곳에만 발신하고, Collector가 trace→Tempo·log→Loki·(보조)metric→Prometheus remote_write로 라우팅한다.

Spring Boot 3.3.5 제약 (구현 확인): management.otlp.tracing은 3.3.5에서 HTTP exporter만 제공한다(gRPC transport 프로퍼티는 3.4+). trace 발신은 Collector HTTP 포트 4318 + /v1/traces를 쓴다. gRPC 포트 4317로 보내면 HTTP POST가 실패해 trace가 유실된다(FR-2 연결율 위협). Collector는 4317/4318 둘 다 수신하므로 web FE가 gRPC를 써도 무방하다.

근거

1. 백엔드 결합 분리 — 앱이 Tempo/Loki 주소·프로토콜을 몰라도 된다. 백엔드 교체·엔드포인트 변경이 Collector config에 국한된다.
2. 단일 발신 지점 — 앱 config가 OTLP 엔드포인트 하나로 단순. OTEL_EXPORTER_OTLP_ENDPOINT 미설정 시 no-op(무중단 배포의 플래그 등가).
3. 가공 지점 확보 — batch·attributes 프로세서로 env resource attribute 보정·샘플링을 Collector에서 일괄 처리.
4. 8GB 제약 대응 — 올인원 이미지(grafana/otel-lgtm) 대신 Collector를 개별 컨테이너로 두되 게이트웨이 역할만 부여해 리소스를 통제.

대안 (미채택)

• 앱이 Tempo/Loki 직결: 백엔드 결합·다중 엔드포인트 config로 앱이 인프라 세부에 결합. 미채택.
• grafana/otel-lgtm 올인원: 컨테이너별 리소스·설정 통제 불가, exporter·Kafka UI 편입·⑧ 분리에 부적합. 미채택(토폴로지 개념만 참조).

영향

• docker-compose.observability.yml에 otel-collector 서비스 1개.
• otel-collector-config.yaml: OTLP receiver(4317/4318) → traces(Tempo)·logs(Loki)·metrics(remote_write) 파이프라인.
• 앱은 management.otlp.tracing.endpoint + logback OTLP appender만 설정.