2. OpenTelemetry 트레이스 발생 실습 (with Kafka )

sky_maru·2025년 8월 17일

OpenTelemetry

목록 보기

2/3

OpenTelemetry 트레이스 발생 실습 (with Kafka )

이 문서는 OpenTelemetry 트레이스를 직접 발생시키는 실습 예제를 통해, 자동 계측과 수동 계측의 차이와 구현 방법을 설명합니다.
Backend는 Kafka, 관측 도구는 Jaeger이며, Jaeger 설정은 [Jaeger] Jaeger 소개, Jaeger 기본 설치에서 확인할 수 있습니다.

1.트레이스를 발생시키는 방법

트레이스(Trace)는 애플리케이션에서 요청이 처리되는 과정을 추적하는 기능으로, 자동 계측(Auto Instrumentation) 과 수동 계측(Manual Instrumentation) 두 가지 방식으로 발생시킬 수 있습니다.

1) 자동 계측 (Auto Instrumentation)

개발자가 직접 코드 수정 없이, OTel에서 제공하는 Java Agent 또는 Instrumentation 라이브러리를 사용하여 트레이스를 자동으로 생성합니다.
웹 프레임워크(Spring, Django 등), DB 클라이언트(JDBC), 메시지 브로커(Kafka), gRPC 등 표준 라이브러리 기반의 호출에 대해 자동으로 Span이 삽입됩니다.
애플리케이션 실행 시 -javaagent 옵션만 추가하면 되므로, 빠르게 도입 가능하며 운영 서비스에 쉽게 붙일 수 있습니다.
예시: Java 애플리케이션 실행 시 자동 계측

java -javaagent:opentelemetry-javaagent.jar \
     -Dotel.exporter.otlp.endpoint=http://otel-collector:4317 \
     -Dotel.service.name=my-service \
     -jar my-app.jar

2) 수동 계측 (Manual Instrumentation)

개발자가 직접 OpenTelemetry SDK를 사용하여 원하는 위치에 Span을 생성하고 종료하는 방식입니다.
자동 계측이 커버하지 못하는 커스텀 로직, 내부 라이브러리, 특정 비즈니스 구간에 대해 세밀한 제어가 가능합니다.
코드에 의존성을 추가하고, 필요한 구간마다 Tracer를 활용해 Span을 정의해야 합니다.
예시: Java SDK를 사용한 수동 계측

Span span = tracer.spanBuilder("DB Query").startSpan();
try {
    // 실제 DB 쿼리 실행 로직
} finally {
    span.end();
}

3) 자동 계측 vs 수동 계측 비교

항목	수동 계측 (Manual Instrumentation)	자동 계측 (Auto Instrumentation)
Span 생성 주체	개발자가 코드로 직접 `Tracer`, `Span` 삽입	Agent가 자동으로 라이브러리 감지해서 생성
코드 수정 필요	필요 (`tracer.spanBuilder(...)`)	불필요
트레이스 범위 제어	개발자가 원하는 위치에 삽입 가능	범용적이지만 제어 어려움
설치 방법	OpenTelemetry SDK 의존성 추가 + 코드 수정	`-javaagent:path/to/opentelemetry-javaagent.jar`
사용 주체	주로 내부 라이브러리/커스텀 로직	Kafka Client, JDBC, gRPC 등 표준 라이브러리 기반 앱