OpenTelemetry Demo 실습: 결제 실패를 트레이스로 따라가기

OpenTelemetry Demo 3.1.0을 Docker Compose로 실행해 정상 주문과 실패한 결제를 Jaeger에서 비교하고, Collector에서 Guance로 트레이스를 보내는 방법을 설명합니다.

모범 사례
애플리케이션 텔레메트리를 살펴보는 일러스트

OpenTelemetry Demo에서는 결제를 한 번 실패시켜 보면 트레이스가 왜 필요한지 바로 드러난다. 브라우저에서 보이는 건 주문이 실패했다는 사실이다. 트레이스를 열면 주문 처리가 결제 서비스까지 도달했는지, 청구 단계에서 어떤 오류가 났는지 확인할 수 있다. 공식 샘플 애플리케이션인 Astronomy Shop에는 이 흐름을 살펴볼 수 있는 계측이 이미 들어 있다.

이 글은 Demo 3.1.0을 기준으로 한다. 해당 버전의 소스로 Compose 구성, 프록시 경로, 결제 핸들러의 동작을 확인했다. 전체 컨테이너 스택 실행과 외부 DataKit 수집은 검증 범위에 포함하지 않았다.

관측 백엔드를 포함해 Demo 실행하기

Astronomy Shop은 스토어 화면, 상품 카탈로그, 장바구니, 주문, 결제 등 여러 언어로 구현한 서비스로 구성된다. 전체 구성에서는 Kafka를 띄우고 부정 거래 감지와 회계 서비스가 메시지를 처리한다. Collector가 텔레메트리를 받고 Jaeger, Prometheus, OpenSearch, Grafana 등에서 데이터를 확인할 수 있다. 서비스마다 내보내는 신호가 다르므로 찾는 데이터가 있으면 서비스별 텔레메트리 목록부터 확인한다. Demo 아키텍처(영어) · 텔레메트리 목록(영어)

Docker와 Compose v2가 설치된 실습 전용 머신을 사용한다. 공식 가이드의 전체 구성 기준은 애플리케이션 메모리 6 GB와 디스크 14 GB다. 이 Compose 설정은 호스트 경로와 Docker 소켓을 마운트하고 여러 포트를 공개한다. 격리된 환경에서 제공된 샘플 데이터로 실습한다. Docker 배포 요구사항(영어) · 3.1.0 릴리스(영어)

git clone --branch 3.1.0 --depth 1 https://github.com/open-telemetry/opentelemetry-demo.git
cd opentelemetry-demo
export DEMO_VERSION=3.1.0
docker compose --env-file .env --env-file .env.override \
  -f compose.yaml -f compose.full.yaml \
  -f compose.observability.yaml -f compose.extras.yaml up -d

docker compose up만 실행하면 기본 구성만 읽는다. 위 명령은 Kafka가 포함된 전체 구성, 로컬 관측 백엔드, 추가 설정을 차례로 적용한다. 스토어와 관측 도구가 준비되면 기본 포트에서 아래 경로를 연다.

로컬 URL 확인할 내용
http://localhost:8080/ 스토어에서 테스트 주문을 넣는다.
http://localhost:8080/jaeger/ui/ 해당 주문의 트레이스를 찾는다.
http://localhost:8080/grafana/ 미리 구성된 대시보드와 데이터 소스를 본다.
http://localhost:8080/loadgen/ 부하 생성기가 보내는 테스트 트래픽을 확인한다.
http://localhost:8080/feature/ flagd UI에서 장애 시나리오를 켜고 끈다.
http://localhost:8080/telemetry/ 서비스별로 문서화된 텔레메트리를 확인한다.

정상 주문과 실패한 결제 비교하기

paymentFailure를 off로 두고 샘플 결제 정보로 주문을 한 번 넣는다. 주문 시각을 기록하고 Jaeger에서 checkout 서비스를 골라 해당 시간대의 트레이스를 찾는다. 이어서 payment 서비스의 charge 스팬을 연다. 부하 생성기의 요청에 묻히면 검색 시간 범위를 줄이거나 비교하는 동안 부하를 잠시 멈춘다.

flagd UI에서 paymentFailure의 기본 variant를 100%로 바꾸고 저장한다. 샘플 주문을 다시 넣으면 이 버전의 결제 핸들러는 테스트용 예외를 발생시키고 charge 스팬에 오류 상태를 기록한다. 두 트레이스를 나란히 놓고 오류가 처음 나타난 스팬을 찾아본다. 실습이 끝나면 플래그를 off로 돌린다. 기능 플래그(영어) · 3.1.0 결제 핸들러

스팬은 한 건의 주문에서 일어난 일을 보여 준다. 같은 시간대에 실패가 늘었는지는 메트릭으로 볼 수 있다. 해당 서비스가 로그를 남기고 트레이스 ID를 확인할 수 있으면 실패한 요청의 로그를 더 좁혀 볼 수 있다. 로그가 없으면 먼저 서비스의 로그 출력 여부와 Collector의 로그 파이프라인을 살핀다.

Collector에서 데이터가 어디로 가는지 확인하기

애플리케이션은 OTLP로 Demo의 Collector에 데이터를 보낸다. 기본 설정에서 수신기와 처리 단계를 지정한다. 관측 계층 설정을 추가하면 트레이스는 Jaeger, 메트릭은 Prometheus, 로그는 OpenSearch로 전달된다. span_metrics 커넥터는 스팬에서 메트릭도 만든다. 마지막 설정 파일을 이용하면 애플리케이션을 변경하지 않고 내보낼 곳을 추가할 수 있다. Collector 기본 설정 · 관측 계층 설정

전체 구성에서는 주문이 Kafka 컨슈머로 이어지는 흐름도 추적해 볼 수 있다. 비동기 작업을 볼 때는 스팬의 부모·자식 관계와 링크를 구분한다. 샘플링을 실습할 때는 트레이싱 정책을 조정하고 어떤 트레이스가 남는지 본다. 실습 환경에서 발생하는 트래픽 자체를 줄이려면 부하 생성기를 조정한다. 트레이스 샘플링만으로 메트릭과 로그가 일괄적으로 줄지는 않는다.

같은 트레이스를 Guance로 보내기

Collector 컨테이너에서 사설 네트워크로 DataKit에 연결할 수 있다면 트레이스부터 복제한다. src/otel-collector/otelcol-config-extras.yml에 OTLP/HTTP Protobuf 익스포터를 추가한 뒤 기존 트레이스 파이프라인에 연결한다. 예제 URL은 컨테이너가 접근할 수 있는 실제 수신 주소로 바꾼다. DataKit의 기본 HTTP 포트는 9529이고 기본 트레이스 경로는 /otel/v1/traces다. TLS와 인증은 배포 환경에 맞춰 설정한다. DataKit OpenTelemetry 연동

exporters:
  otlp_http/datakit:
    traces_endpoint: https://datakit.example.com/otel/v1/traces
service:
  pipelines:
    traces:
      exporters: [debug, otlp_grpc/jaeger, span_metrics, otlp_http/datakit]

Collector가 설정 파일을 합칠 때 배열은 덮어쓰인다. 기존 출력을 유지하려면 Jaeger, 디버그 익스포터, span_metrics 커넥터를 배열에 함께 넣어야 한다. 변경 후 같은 Compose 구성으로 Collector를 다시 시작한다. 트레이스가 들어오면 정상 주문과 실패 주문을 기준으로 Guance에서 서비스 이름과 스팬 계층을 비교한다. 메트릭과 로그도 보내려면 신호별 엔드포인트와 파이프라인을 따로 연결한다.

실습 중 자주 나오는 질문

전체 구성이 너무 무거우면? 공식 최소 구성은 관측 스택을 유지하고 Kafka와 그에 의존하는 서비스를 뺀다. 공식 가이드의 애플리케이션 메모리 기준은 약 3 GB다. 의존성을 유지하려면 지원되는 구성을 사용한다.

계측 코드를 운영에 가져가도 되나? 사용 언어의 SDK 예제부터 보고 리소스 식별 정보, 샘플링, 민감 데이터 정책을 운영 환경에 맞춘다. 실습에서는 샘플 데이터를 쓰고 민감 데이터를 원문으로 출력하는 플래그는 꺼 둔다.

Kubernetes에서도 실행할 수 있나? 업스트림에서 Helm 차트를 제공한다. 테스트 클러스터에서 문서에 나온 values, 리소스 요구사항, 포트 포워딩 방법을 따른다. Kubernetes 배포(영어)

함께 읽기

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소