5.2. 분산추적
전체 추적(Trace) 데이터를 탐색하고, 서비스 간 요청 흐름을 분석하는 화면입니다.
개요
분산추적 화면은 마이크로서비스 환경에서 요청이 여러 서비스를 거치는 전체 경로를 시각화합니다. 추적(Trace)은 분산 시스템에서 하나의 요청이 여러 서비스를 거치는 경로를 기록한 데이터입니다.
히트맵(Heatmap)으로 추적 데이터의 분포를 한눈에 파악하고, 응답 시간이 느린 요청이나 오류가 발생한 요청을 빠르게 식별할 수 있습니다. 선택한 영역을 드릴다운하여 개별 추적의 스팬(Span) 상세까지 확인할 수 있습니다.
좌측 사이드바에서 분산추적 메뉴를 클릭하면 진입할 수 있습니다.
참고: 분산추적 데이터는 OpenTelemetry SDK로 계측된 애플리케이션에서 수집됩니다. 아직 연동하지 않은 경우 화면 상단의 OpenTelemetry 통합 버튼을 클릭하여 설정 방법을 확인하세요.
화면 구성
| 영역 | 설명 |
|---|---|
| 상단 헤더 | OpenTelemetry 통합 버튼 |
| 히트맵 | X축(시간) x Y축(응답 시간) 분포 차트. 드래그로 범위 선택 가능 |
| 탭 | 개요 / 추적 / 오류 원인 / 응답 시간 탐색기 / 속성 비교 |
| 필터 패널 | 서비스명, 스팬명, 추적 ID 등의 필터 조건 설정 |
| 차트 선택 표시 | 히트맵에서 선택된 시간·응답 시간 범위 표시 |
| 기준선 표시 | 속성 비교, 응답 시간 탐색기 탭에서 선택 영역 외의 비교 기준 표시 |
| 옵션 | 보조 요청 제외 설정 |
| 콘텐츠 영역 | 탭별 분석 결과 표시 |
주요 기능
히트맵 읽는 법
히트맵(Heatmap)은 시간과 응답 시간의 분포를 색상 밀도로 시각화합니다. 가로축(X축)은 시간, 세로축(Y축)은 추적의 응답 시간을 나타냅니다. 각 셀의 색상은 해당 시간대·응답 시간 범위에 속하는 요청의 밀도를 표현합니다.
- 색상이 진할수록 해당 시간대에 해당 응답 시간 범위의 요청이 많이 발생했음을 의미합니다.
- 색상이 위쪽에 집중되어 있으면, 응답 시간이 긴 요청이 많다는 뜻입니다.
- 특정 시간대에 붉은 점이 나타나면, 그 시점에 오류가 발생했음을 나타냅니다.
- 정상적인 상태에서는 대부분의 점이 **아래쪽(낮은 응답 시간)**에 집중됩니다.
히트맵 좌측 상단에 색상 범례가 표시됩니다. 범례의 왼쪽(밝은색)은 요청이 적은 영역, 오른쪽(진한색)은 요청이 많은 영역을 나타냅니다.
SLO 응답 시간 목표가 설정된 경우, 히트맵에 목표 임계값 라인이 표시됩니다. 이 라인 위의 요청은 SLO 목표를 초과한 요청 입니다.
히트맵 우측의 확대 버튼을 클릭하면 전체 화면 모드에서 히트맵을 더 넓게 확인할 수 있습니다.
히트맵 영역 선택
히트맵에서 마우스로 드래그하여 특정 시간·응답 시간 범위를 선택할 수 있습니다. 선택하면 해당 범위의 추적 데이터만 탭에 표시됩니다.
- 히트맵에서 조사하려는 영역을 마우스로 클릭한 채로 드래그합니다.
- 선택된 범위가 차트 선택 행에 시간 범위와 응답 시간 범위 태그로 표시됩니다.
- 오류 영역을 선택한 경우 오류 태그도 함께 표시됩니다.
- 탭의 콘텐츠가 선택한 범위 기준으로 자동 갱신됩니다.
- 선택을 취소하려면 차트 선택 행의 선택 해제 버튼을 클릭합니다.
팁: 응답 시간이 급증한 영역(히트맵 위쪽의 점 클러스터)을 선택한 뒤 추적 탭이나 오류 원인 탭을 확인하면 문제의 원인을 빠르게 파악할 수 있습니다.
탭별 분석
개요 탭
전체 추적 데이터의 요약 정보를 보여줍니다.
상단 요약 카드에서 다음 지표를 확인할 수 있습니다.
| 지표 | 설명 |
|---|---|
| 서비스 | 추적에 포함된 고유 서비스 수 |
| 요청 | 초당 전체 요청 수 (/s) |
| 오류 | 전체 요청 중 오류 비율 (%) |
| p50 / p95 / p99 | 응답 시간 백분위수 (밀리초) |
하단 테이블에는 루트 서비스(Root Service)와 루트 스팬(Root Span) 이름별로 요청 수, 오류율, 응답 시간 백분위수가 표시됩니다.
참고: 이 테이블은 루트 스팬만 표시합니다. 루트 스팬(Root Span)은 각 추적(Trace)에서 요청이 시작되는 첫 번째 스팬입니다.
테이블에서 다음 작업을 수행할 수 있습니다.
- 서비스명(루트 서비스) 클릭: 해당 서비스의 샘플 추적 상세(스팬 폭포수 차트) 다이얼로그가 열립니다.
- 스팬명 클릭: 해당 서비스·스팬으로 필터링된 추적 탭으로 이동합니다.
- 오류율 클릭: 해당 서비스·스팬의 오류 원인 탭으로 이동합니다.
- 필터 아이콘: 해당 스팬으로 필터를 적용합니다.
- 추적 아이콘: 샘플 추적의 스팬 폭포수 차트를 엽니다.
참고: 루트 서비스(Root Service)는 요청이 처음 진입하는 서비스입니다. p50/p95/p99는 전체 요청 중 각각 50%, 95%, 99%가 해당 응답 시간 이내에 처리됨을 의미합니다.
추적 탭
조회된 개별 추적 목록을 테이블로 보여줍니다.
| 컬럼 | 설명 |
|---|---|
| 추적 ID | 추적의 고유 식별자 (앞 8자리 표시) |
| 루트 서비스 | 요청이 처음 진입한 서비스 이름 |
| 이름 | 루트 스팬의 오퍼레이션 이름 |
| 상태 | OK(정상) 또는 Error(오류) |
| 응답시간 | 전체 추적의 소요 시간 (밀리초). 막대 그래프로 상대적 크기도 함께 표시 |
추적 ID 또는 이름을 클릭하면 해당 추적의 스팬 폭포수 차트가 다이얼로그로 열립니다.
참고: 조회 결과가 많을 경우 최대 건수 제한 안내 메시지가 표시될 수 있습니다. 히트맵에서 좀 더 좁은 범위를 선택하거나 필터를 추가하여 범위를 줄이세요.
오류 원인 탭
선택된 범위의 추적에서 오류가 발생한 스팬(Span)을 분석하여 보여줍니다.
이 탭은 단순히 오류가 있는 추적을 나열하는 것이 아니라, 어느 서비스의 어느 스팬에서 오류가 기 원했는지를 강조합니다.
| 컬럼 | 설명 |
|---|---|
| 서비스 이름 | 오류가 발생한 서비스 |
| 스팬 | 오류가 발생한 스팬 이름 및 레이블 |
| 오류 | 오류 메시지 |
| 샘플 추적 | 해당 오류를 포함한 샘플 추적 ID (클릭 시 스팬 상세 열림) |
| 백분율 | 전체 요청 중 해당 오류가 차지하는 비율 |
샘플 추적 링크를 클릭하면 해당 오류가 포함된 실제 추적의 스팬 폭포수 차트를 확인할 수 있습니다.
응답 시간 탐색기 탭
선택된 추적의 응답 시간 분포를 플레임 그래프(Flame Graph)로 시각화합니다.
플레임 그래프(Flame Graph)는 함수 호출 스택과 소요 시간을 시각화합니다. 각 블록의 너비가 넓을수록 해당 스팬에서 더 많은 시간을 소비했다는 의미입니다.
- 블록을 클릭하면 해당 스팬을 포함한 샘플 추적의 스팬 폭포수 차트를 열 수 있습니다.
- 히트맵에서 특정 영역을 선택한 후 이 탭을 확인하면, 선택된 요청들에서 어느 스팬이 병목인지 파악하는 데 도움이 됩니다.
속성 비교 탭
히트맵에서 선택한 영역의 추적(선택)과 같은 시간 윈도우 내의 다른 추적(기준선)의 속성 분포를 비교합니다.
선택 영역에서 평소보다 특정 속성 값의 비율이 높다면, 그 속성이 문제의 원인과 관련이 있을 가능성이 있습니다.
각 속성은 카드 형태로 표시되며, 카드 내부에는 속성 값별로 기준선(Baseline)과 선택 영역(Selection)의 비율이 막대 그래프로 비교됩니다.
팁: 응답 시간이 느린 구간을 히트맵에서 선택한 뒤 속성 비교 탭을 확인하면, 특정 HTTP 상태 코드, 사용자 에이전트, 데이터베이스 테이블 등 특이 속성을 빠르게 식별할 수 있습니다.
각 속성 카드에서 속성 값을 클릭하면 해당 속성을 포함한 샘플 추적의 스팬 폭포수 차트를 확인할 수 있습니다.
필터 사용
필터를 추가하면 특정 서비스, 스팬, 추적 ID에 해당하는 추적만 조회할 수 있습니다.
필터를 추가하는 방법:
-
필터 행의 필터 추가 버튼을 클릭합니다.
-
필드 드롭다운에서 필터링할 항목을 선택합니다.
필드 설명 루트 서비스 이름 요청이 처음 진입한 서비스 이름 루트 스팬 이름 루트 스팬의 오퍼레이션 이름 추적 ID 특정 추적의 고유 ID -
연산자를 선택합니다.
연산자 의미 =일치 !=불일치 ~포함 !~미포함 -
값을 입력합니다.
-
체크 버튼을 클릭하여 필터를 적용합니다.
적용된 필터는 칩(chip) 형태로 표시됩니다. 칩을 클릭하면 수정할 수 있고, 칩의 X 버튼을 클릭하면 해당 필터가 삭제됩니다. 모든 필터를 한 번에 제거하려면 전체 해제 버튼을 클릭합니다.
참고: 필터를 여러 개 추가하면 모든 조건을 동시에 만족하는 추적만 조회됩니다.
옵션: 보조 요청 제외
필터 패널의 옵션 행에서 모니터링, Kubernetes 관리서버 등의 보조 요청 제외 체크박스를 설정할 수 있습니다.
이 옵션을 활성화하면(기본값) Kubernetes 내부 관리 요청, 모니터링 헬스체크 등의 보조 요청이 분석 결과에서 제외됩니다. 실제 사용자 요청만 분석하려는 경우 이 옵션을 켜두세요.
추적 상세: 스팬 폭포수 차트
추적 목록에서 추적 ID나 이름을 클릭하면, 해당 추적의 스팬 폭포수 차트(Span Waterfall Chart)가 다이얼로그로 열립니다.
스팬 폭포수 차트는 요청이 각 서비스를 거치는 순서와 소요 시간을 시각화합니다.
다이얼로그 상단에 추적의 요약 정보가 표시됩니다.
| 항목 | 설명 |
|---|---|
| 시작 시간 | 추적이 시작된 시각 |
| 응답 시간 | 추적의 전체 소요 시간 (밀리초) |
| 상태 | 정상(OK) 또는 오류(Error) |
차트는 좌측의 서비스 & 작업 영역과 우측의 시간축 영역으로 구성됩니다.
- 가로 막대의 시작 위치는 스팬이 시작된 시점, 길이는 해당 스팬의 소요 시간을 나타냅니다.
- 각 스팬의 서비스 이름은 고유한 색상으로 구분됩니다.
- 자식 스팬은 들여쓰기로 계층 구조를 표현합니다. 상위 스팬의 이름을 클릭하면 하위 스팬을 접거나 펼칠 수 있습니다.
- 오류가 발생한 스팬에는 오류 아이콘이 표시됩니다.
- 하위 추적 보기 / 전체 추적 보기를 전환하여, 특정 서비스의 하위 스팬만 보거나 전체 추적을 볼 수 있습니다.
스팬에 마우 스를 올리면 서비스명, 오퍼레이션명, 응답 시간, 상태, 자식 스팬 수, 유형(HTTP, gRPC, Kafka 등) 정보가 툴팁으로 표시됩니다.
스팬 상세 정보 확인
스팬의 가로 막대 또는 정보 버튼을 클릭하면 해당 스팬의 상세 정보 다이얼로그가 표시됩니다.
| 항목 | 설명 |
|---|---|
| 이름 | 스팬의 오퍼레이션 이름 |
| 서비스 | 스팬이 속한 서비스 이름 |
| 시작 시간 | 스팬 시작 시각 |
| 응답시간 | 스팬 소요 시간 (밀리초) |
| 상태 | 정상(OK) 또는 오류(Error) 및 메시지 |
| 스팬 ID | 스팬의 고유 식별자 (복사 가능) |
| 상세 | 프로토콜별 상세 정보 (SQL 쿼리, HTTP 요청 등). 구문 강조가 적용되며 복사할 수 있습니다. |
| 속성 | 스팬에 첨부된 속성 목록 (HTTP URL, DB 쿼리 등). 각 값을 개별 복사할 수 있습니다. |
| 이벤트 | 스팬 실행 중 발생한 이벤트 (예: 예외 스택 정보). 이벤트 발생 시점이 스팬 시작 이후 경과 시간으로 표시됩니다. |
스팬 유형은 배지로 표시됩니다. 지원하는 유형은 다음과 같습니다.
| 유형 | 설명 |
|---|---|
| HTTP | HTTP 요청/응답 |
| gRPC | gRPC 호출 |
| Kafka | Kafka 메시지 처리 |
| Redis | Redis 명령 |
| Mongo | MongoDB 쿼리 |
| PostgreSQL | PostgreSQL 쿼 리 |
| MySQL | MySQL 쿼리 |
| CH | ClickHouse 쿼리 |
| ZK | ZooKeeper 작업 |
| MC | Memcached 작업 |
OpenTelemetry 통합
화면 상단 헤더의 OpenTelemetry 통합 버튼을 클릭하면 애플리케이션 계측 설정 가이드 다이얼로그가 열립니다.
OpenTelemetry는 추적(Trace), 메트릭(Metric), 로그(Log)를 수집하는 오픈소스 관측 표준입니다. Java, Python, Go, Node.js, .NET 등 다양한 언어의 SDK를 통해 애플리케이션 코드에서 추적 데이터를 OPENMARU Observability로 전송할 수 있습니다.
다이얼로그에서 다음 정보를 확인할 수 있습니다.
- OPENMARU Observability URL: 추적 데이터를 전송할 엔드포인트 주소 (복사 가능)
- API 키: 인증에 필요한 키 (복사 가능)
- SDK별 연동 가이드: 사용하는 프로그래밍 언어에 맞는 설정 코드와 환경 변수
참고: eBPF 기반 자동 추적도 지원됩니다. 코드 수정 없이 수집된 추적 데이터는 애플리케이션 상세의 분산추적 탭에서 확인할 수 있습니다. 이 화면(분산추적 메뉴)은 OpenTelemetry SDK 계측 데이터를 주로 보여줍니다.
활용 시나리오
느린 요청 원인 분석
- 분산추적 화면에서 히트맵 상단(높은 응답 시간 영역)에 점이 집중된 시간대를 찾습니다.
- 해당 영역을 드래그하여 선택합니다.
- 개요 탭에서 어느 서비스의 응답 시간이 높은지 확인합니다.
- 추적 탭에서 개별 추적을 클릭하여 스팬 폭포수 차트를 확인합니다.
- 스팬 폭포수 차트에서 가장 넓은 막대(오래 걸린 스팬)를 클릭하여 상세 속성을 확인합니다.
- 속성 비교 탭에서 느린 요청의 공통 속성(특정 엔드포인트, 데이터베이스 쿼리 등)을 파악합니다.
오류 원인 추적
- 히트맵에서 오류가 표시된 영역(붉은 점)을 선택합니다.
- 오류 원인 탭에서 오류가 발생한 서비스와 스팬을 확인합니다.
- 샘플 추적 링크를 클릭하여 오류가 발생한 실제 추적의 스팬 상세를 확인합니다.
- 스팬의 이벤트 섹션에서 예외 스택 정보를 확인합니다.
특정 요청 추적
- 분산추적 화면에서 필터 추가 버튼을 클릭합니다.
- 필드에서 추적 ID를 선택하고, 연산자를 **=**로 설정한 뒤, 값에 추적 ID를 입력합니다.
- 체크 버튼을 클릭하여 필터를 적용하면, 해당 추적이 추적 탭에 바로 표시됩니다.
- 추적 ID를 클릭하여 스팬 폭포수 차트에서 요청의 전체 경로를 확인합니다.
서비스별 성능 비교
- 개요 탭의 테이블에서 각 루트 서비스의 요청 수, 오류율, p50/p95/p99 응답 시간을 비교합니다.
- p99 컬럼 옆의 응답 시간 막대 그래프로 서비스 간 상대적 성능 차이를 시각적으로 파악합니다.
- 오류율이 높은 서비스의 오류율 배지를 클릭하면 해당 서비스의 오류 원인 탭으로 이동합니다.