dpdpdndn 블로그

ADR-001 OTel 계측 방식 = Micrometer Tracing + OTel Bridge

NEW3 min read

ADR-001 OTel 계측 방식 = Micrometer Tracing + OTel Bridge

  • 상태: 채택
  • 날짜: 2026-07-03
  • 근거: PRD FR-2 / TDD “Possible Solutions — OTel 계측 방식”

맥락

backend는 이미 Micrometer 계측 자산(Tomcat/JVM/GC 메트릭 + env 태그)을 갖고 있고, registry만 Datadog→Prometheus로 교체한다(FR-1). 여기에 분산 추적을 신규 도입해야 한다(FR-2). PRD는 “Java Agent 또는 Micrometer Tracing + OTel Bridge” 두 선택지를 열어뒀다. Spring Boot 3.3.5, 표준 JVM(GraalVM native 아님).

결정

Micrometer Tracing + OTel Bridge를 채택한다. micrometer-tracing-bridge-otel + opentelemetry-exporter-otlp 의존성을 추가하고, management.tracing·management.otlp.tracing config로 OTLP를 Collector에 전송한다. 메트릭 경로는 기존 Micrometer(/actuator/prometheus)를 그대로 유지한다.

근거

  1. 메트릭 이중 파이프라인 회피 — Java Agent는 메트릭도 OTLP로 push한다. FR-1은 /actuator/prometheus scrape 재사용을 못박았으므로, Agent를 쓰면 scrape 경로와 OTLP push 경로가 병존해 메트릭이 이중 집계된다. Micrometer Tracing은 trace만 OTLP로 보내고 메트릭은 scrape로 유지 → 경로가 깔끔히 분리된다.
  2. env 태그 단일 관리(FR-8) — Micrometer는 management.metrics.tags.env 한 곳에서 태그를 부여하고, OTel resource deployment.environment로 매핑하면 metric·trace가 같은 config 원천을 공유한다. Agent는 resource attribute를 별도 환경변수로 재정의해 이중 관리가 된다.
  3. 버전 결합 리스크 없음 — Agent는 라이브러리 바이트코드를 수정해 버전에 강결합한다(v1→v2에서 Spring 애노테이션 추적이 기본 중단된 전례). Micrometer Tracing은 Spring Boot 3.3.5가 1급 지원하는 추상화라 OTel 버전 변화에 완충된다.
  4. 신규 계측 코드 최소 — HTTP in/out은 Observation API가 자동 계측. Kafka는 isObservationEnabled=true 옵션 한 줄로 전파. FR-5 Spring 메트릭은 코드 0.

대안 (미채택)

  • OpenTelemetry Java Agent: 무코드 계측이 매력적이나 위 1·3 사유로 이 과제의 FR-1(scrape 재사용)과 상충. 미채택.
  • 수동 OTel SDK 계측: 전 구간 수동 span은 누락 위험·노동 과다, 지금 규모에 과함. 미채택.

영향

  • build.gradle.kts에서 micrometer-registry-datadog 제거 + micrometer-registry-prometheus·micrometer-tracing-bridge-otel·opentelemetry-exporter-otlp 추가.
  • Kafka trace 전파를 위해 KafkaConsumerConfig·KafkaProducerConfig에 observation 옵션 추가.
  • trace 연결율 99% 목표는 HTTP(자동)+Kafka(옵션)+JDBC(자동) 전파로 달성.

그래프 뷰