왜 ‘흐름’이 필요했을까?

모놀리식 환경에선 호출이 한 덩어리라 비교적 직관적이다.
로그 몇 줄만 봐도 “어디서 무슨 일이 났는지” 감이 온다.

하지만 서비스가 나뉘는 순간, 로그는 섞이고 타임라인은 흐트러진다.
“200 OK”만 보고는 흐름 전체를 신뢰할 수 없는 상황이 발생한다.

그래서 설계 목표를 이렇게 잡았다:

• 로그는 눈으로 따라가기 쉽게 (MDC 전파)
• 트레이스는 화면에서 추적 가능하게 (OTLP Exporter → Collector → Tempo)
• 메트릭스는 지표 기반으로 확인 가능하게 (Micrometer → Prometheus → Grafana)
• 즉, 로그·트레이스·메트릭을 하나의 사건으로 묶는 것

이번 글에서는 이런 배경 위에서, 실제로 어떻게 테스트하고 검증했는지를 중심으로 풀어가려 한다.

---

💣 시작은 단순 UUID였다

초기엔 요청마다 UUID 하나를 붙였다. 모놀리식에선 충분하다고 생각했다.
하지만 MSA에선 요청이 A → B → C로 흘러간다.
서비스 경계를 넘을 때마다 UUID가 새로 생기면, 한 번의 사용자 요청을 하나의 타임라인으로 볼 수 없다.

즉, MSA에선 서비스 경계를 넘는 순간, 단일 ID만으론 전체 호출 트리 시각화를 만들 수 없다는 것이다.

그래서 수동 UUID는 버리고, Micrometer Tracing을 도입해 traceId/spanId를 자동 생성·전파하도록 했다.

• traceId: 전체 요청의 흐름을 하나로 묶는 ID
• spanId: 그 요청 내 각 단위 작업(HTTP 요청, DB 쿼리 등)에 대한 ID
• MDC 전파: 로그가 어디서 찍히든 같은 언어로 기록

예시 :

[traceId: AAA]  
├── spanId: A1 (Gateway)  
│   ├── spanId: B1 (Service A: Controller)
│   │   └── spanId: C1 (Service A: DB)
│   └── spanId: B2 (Service B: External API)
└── spanId: A2 (Service C) 

✅ `traceId`: AAA "요청 전체 식별자"
✅ 각각의 `spanId`: "실제 작업의 구체적 위치"

→ 하나의 traceId 안에는 여러 spanId가 있고, 이들은 트리 구조로 연결됨 (parent/child)

또한 MdcKeys 키는 enum 말고 public final class MdcKeys로 문자열 상수로 관리하여 별도 분리해주고, 필터에서 가져다가 사용하였다.
➡️ 장점 : 로그백 패턴%X{}는 문자열 키만 받기도 하고, 한 군데만 고치면 전역 반영 가능

MDC는 내부적으로는 ThreadLocal<Map<String, String>> 구조로 동작한다.

마지막으로 MDC.put()으로 주입해주고, 요청이 끝난 시점에서 ThreadLocal 값을 명시적으로 비워줘야 다음 요청에서 잘못된 값이 섞이는 버그 + 메모리 누수를 방지하기위해 MDC.clear()로 마무리하였다.

---

❓ traceId는 생성했으니, 이제 전파와 시각화는 어떻게 할까

그래서 자동 traceId 관리에서 한 걸음 더 나아가, 서비스 간 호출 흐름 추적과 시각화까지 고려해 Micrometer Tracing + OpenTelemetry를 도입했다.

처음엔 애플리케이션에서 Tempo 같은 백엔드로 직접 전송을 고민했다.
곧바로 막혔다. 백엔드를 바꾸거나, 여러 군데로 동시에 보내거나, 네트워크 이슈에 방어적으로 대응하기가 만만치 않았다.

그래서 Exporter를 바로 붙이지 않고, 중간에 OpenTelemetry Collector를 세웠다.

• 애플리케이션 → OTLP(HTTP 4318 / gRPC 4317) → Collector
• Collector에서 집계·샘플링·라우팅·포맷 변환
• 뒷단은 Grafana Tempo로 시각화 (초기 Zipkin에서 전환)

백엔드를 갈아끼우거나 전송 정책을 조정할 때 앱 수정이 필요 없게 만드는 게 포인트였다.

App → OTLP(4317/4318) → Collector → Tempo (or Zipkin, Jaeger)

Collector를 쓰니 애플리케이션은 “흐름 만들기”에만 집중할 수 있었고,
백엔드를 갈아끼우거나 전송 정책을 바꿀 때도 앱 수정 없이 Collector 설정만 변경하면 됐다.

추가로, Collector는 동시에 여러 Exporter로 전송할 수 있어 운영 환경에서는
Tempo + Jaeger 같은 멀티 전송도 가능하다.

즉, Collector는 단순 중계기가 아니라 확장성과 유연성을 보장하는 중앙 허브였다.

---

🛰️ MSA 호출, 단일 앱에서 두 서비스로 확장하기

처음에는 단일 애플리케이션 내부에서 A→B 호출을 흉내 내며 테스트했다.

📂 폴더 구조 (단일 앱 안에서 A와 B를 나눈 형태)

tracing/
 ├─ client/
 │   └─ BServiceClient
 ├─ controller/
 │   ├─ AController
 │   └─ BController
 ├─ service/
 │   └─ AService
config/
 └─ tracing/
     └─ TracingWebClientConfig

➡️ 하나의 애플리케이션 안이지만, 패키지를 분리해 A와 B 서비스처럼 구성했다.

---

🔀 호출 흐름 (요청이 실제로 흘러가는 경로)

GET /a/call-b
  → AController
    → AService
      → BServiceClient (WebClient)
         → GET /b/hello
            → BController

• WebClient(리액티브, Spring WebFlux 기반) 로 A→B 호출을 구현했다.
• Micrometer Tracing 으로 traceId/spanId를 자동 전파했다.
• MDC 를 통해 로그에도 동일 ID를 주입했다.

덕분에 Postman 호출만으로도 로그 + Tempo 시각화를 동시에 확인할 수 있었다.

하지만 곧 한계가 보였다.
→ 같은 애플리케이션 내부에서만 호출을 흉내 내다 보니, 실제 MSA처럼 서비스 경계를 넘는 흐름을 온전히 증명하긴 어려웠다.

더 명확한 테스트를 위해 실제 MSA처럼 서비스를 분리한 구조에서 보는 것이 더 적합하다고 판단했다.

👉🏻 그래서 호출 구조는 그대로 두고, 8081(logsentry-api)와 8082(service-b) 두 서비스로 나누어 테스트를 진행했다.

[Before: 단일 애플리케이션]
  logsentry-api (8081)
    ├─ AController
    ├─ AService
    ├─ BServiceClient
    └─ BController
    (TraceId/SpanId 동일 JVM 내 전파)

----------------------------

[After: 서비스 분리]
  Service-A (8081, logsentry-api)
    └─ /a/call-b
         └─ WebClient → Service-B 호출

  Service-B (8082, service-b)
    └─ /b/hello

---

⚙️ 서비스 분리 구성

먼저 기존 service-a(logsentry-api)에서 service-b를 호출할 수 있도록 구조를 바꿨다.
나는 모든 서비스를 Docker 환경에서 실행했기 때문에, service-b 컨테이너를 먼저 추가하였다.

1. service-b 도커 컨테이너 추가

# docker-compose.yml
service-b:
  build:
    context: ./service-b
    dockerfile: Dockerfile
  container_name: service-b
  ports:
    - "8082:8082"
  environment:
    - SPRING_PROFILES_ACTIVE=${SPRING_PROFILES_ACTIVE}
  networks:
    - logsentry
  restart: unless-stopped
  healthcheck:
    test: ["CMD", "wget", "--spider", "-q", "http://localhost:8082/actuator/health"]
    interval: 30s
    timeout: 10s
    retries: 10
    start_period: 60s

---

2. service-a → service-b 호출 구조 변경 및 환경 설정 추가

application-prod.yml

b:
  base-url: ${B_BASE_URL:http://localhost:8082}

BProps (환경변수 주입)

@ConfigurationProperties(prefix = "b")
public record BProps(String baseUrl) {}

TracingWebClientConfig

@Configuration
@RequiredArgsConstructor
@Slf4j
public class TracingWebClientConfig {

    private final BProps props;
    private final Tracer tracer;

    @Bean
    WebClient webClient(WebClient.Builder builder) {
        return builder
            .baseUrl(props.baseUrl())
            .filter((request, next) -> {
                var context = tracer.currentTraceContext().context();
                if (context != null) {
                    log.info("[Tracing] traceId={}, spanId={}", context.traceId(), context.spanId());
                }
                return next.exchange(request);
            })
            .build();
    }
}

BServiceClient

@Component
@RequiredArgsConstructor
public class BServiceClient {

    private final WebClient webClient;

    @Observed(name = "bServiceClient.callB", contextualName = "WebClient → B")
    public Mono<String> callB() {
        return webClient.get()  // http://localhost:8081/b/hello에서 상대 경로로 변경 → service-b 호출
                .uri("/b/hello")
                .retrieve()
                .bodyToMono(String.class);
    }
}

---

✅ service-b 서비스에는 BController와 함께, Tempo/Otel 전송 구조 yml과 Dockerfile 정도의 최소 설정만 두었다.

BController

@RestController
@RequestMapping("/b")
public class BController {

    private static final Logger log = LoggerFactory.getLogger(BController.class);

    @Observed(name = "bController.hello", contextualName = "HTTP /b/hello")
    @GetMapping("/hello")
    public Mono<String> hello() {
        log.info("[B] /b/hello 요청 처리");
        return Mono.just("Hello from B!");
    }
}

---

🔍 Grafana Tempo에서 확인

두 서비스를 구분하기 위해 spring.application.name 을 각각 다르게 설정했다.

• service-a → logsentry-api
• service-b → service-b

Tempo 쿼리는 다음과 같이 지정했다.

{resource.service.name=~"logsentry-api|service-b"}

이 상태에서 /a/call-b 요청을 보내면, Tempo는 아래처럼 span 트리를 보여준다.
그리고, 서비스별로 색이 다르게 표시되어 A→B 호출 흐름을 한눈에 구분할 수 있었다.

1. logsentry-api (서비스 A)

   • http get /a/call-b → 최초 요청, root span
   • 내부에서 WebClient로 /b/hello 호출 시 새로운 child span 생성

2. service-b (서비스 B)

   • http get /b/hello → service-a의 WebClient 호출을 처리
   • 같은 traceId를 공유하므로 Tempo에서 child span으로 이어짐

• root span: /a/call-b (service-a)
• child span: /b/hello (service-b)

→ traceId는 동일하고, spanId만 새로 생성되어 부모-자식 관계로 연결됐다.

👉 결과적으로, /a/call-b (logsentry-api) 요청이 traceId를 유지한 채 /b/hello (service-b)까지 이어지는 흐름을 시각적으로 증명할 수 있었다.

단일 애플리케이션 내에서도 traceId 전파 검증은 가능했다.
하지만 서비스를 실제로 두 개 분리하니, A→B 호출 흐름이 훨씬 명확하게 드러났다.

---

🔥 마무리하며

이번 글의 포인트는 요청이 어디서 시작해 어디까지 갔는지, 그 길을 눈과 화면으로 동시에 따라갈 수 있게 만드는 설계였다.

• 애플리케이션은 Micrometer Tracing으로 traceId/spanId를 MDC와 헤더에 자동 전파했다.
• 전송은 OTLP → Collector로 중앙 집중화했다.
• 시각화는 Grafana Tempo에서 서비스별 트리 구조로 확인했다.
• 테스트는 처음엔 단일 앱 내부에서, 이후 8081↔8082 두 서비스로 분리하여 실제 MSA처럼 검증했다.

이제 “200 OK면 끝”이 아니라, “흐름을 확인하는 습관" 이 정말 중요하다고 체감했다.

_

📘 용어 정리

Micrometer Tracing: Spring Boot 3.x의 Sleuth 후속 분산 추적 라이브러리, traceId/spanId 자동 생성·전파
OpenTelemetry (OTEL): CNCF 표준 관측 프레임워크, 로그·메트릭·트레이스를 통합 관리
OTLP Exporter: 트레이스 데이터를 OTLP 프로토콜(HTTP/gRPC)로 Collector에 전달하는 모듈
Collector: Exporter에서 받은 데이터를 집계·변환·라우팅해 Zipkin, Tempo 등 백엔드로 전송