트레이스

트레이스 (Traces)

트레이스 시각화는 요청이 인프라의 서비스를 통과하면서 이동하는 경로를 따라갈 수 있게 해줘요. 트레이스 데이터를 해석하기 쉬운 다이어그램으로 표시하며, 현재 TraceQL에 사용된 traceID 또는 변수를 기반으로 하나의 트레이스 경로를 렌더링해요. 분산 시스템의 요청 흐름과 병목을 분석할 때 유용합니다.

출처: 문서

본문

트레이스 시각화는 요청이 인프라 서비스를 통과하는 경로를 따라가게 합니다. 트레이스 데이터를 해석하기 쉬운 다이어그램으로 표시하며, 현재 TraceQL의 traceID나 변수를 기반으로 하나의 트레이스 경로를 렌더링합니다.

트레이스 관련 자세한 내용은 다음 문서를 참고하세요.

  • Tracing in Explore
  • Tempo 데이터 소스
  • Getting started with Tempo

트레이스 시각화 패널 추가하기

Grafana 인스턴스에 트레이스 데이터가 있으면 대시보드에 트레이스 패널을 추가할 수 있습니다. 대시보드 변수 traceID를 사용해 특정 trace ID의 트레이스를 보여주는 쿼리를 만들 수 있습니다. 대시보드 변수에 대한 자세한 내용은 Variables 문서를 참고하세요.

시작하기 전에

  • Grafana 인스턴스
  • Grafana 인스턴스에 연결된 Tempo 데이터 소스

단계

이 절차는 템플릿 쿼리로 사용할 traceId 변수를 만듭니다.

  1. Grafana 인스턴스에서: 새 대시보드라면 패널을 클릭·드래그해 추가. 기존 대시보드라면 우측 상단 Edit 클릭 → Add new element 아이콘 클릭 → 패널 추가.
  2. Configure visualization 클릭해 패널 편집 모드 열기.
  3. 쿼리 편집기에서 데이터 소스 목록을 클릭하고 적절한 트레이스 데이터 소스 선택.
  4. 패널 편집기 우측 상단 All visualizations 탭에서 Traces 검색·선택.
  5. Panel options 아래에 트레이스 패널 Title 입력 (또는 generative AI로 생성).
  6. 쿼리 편집기에서 TraceQL 쿼리 유형 탭 클릭.
  7. TraceQL 쿼리 필드에 ${traceId}를 입력해 대시보드 변수 생성.
  8. Back 클릭 → Add new element 아이콘 → Variable 클릭.
  9. traceId 변수 생성, 변수 유형 Custom, 필요시 라벨 지정.
  10. Save 클릭 → 변경 설명 입력 → Save → Exit edit.
  11. 트레이스 패널 데이터 소스에 유효한 trace ID를 대시보드 변수에 입력해 동작 확인.

TraceQL + 테이블 시각화 추가하기

트레이스 ID를 대시보드 변수로 수동 추가하는 것은 번거롭습니다. TraceQL 쿼리로 특정 유형의 트레이스를 검색하고 일치하는 결과에서 트레이스를 선택하는 것이 더 유용합니다.

  1. 트레이스 시각화를 추가한 대시보드에서 Edit 클릭.
  2. Add new element 아이콘 → 패널 추가.
  3. Configure visualization 클릭 → 이전과 같은 트레이스 데이터 소스 선택.
  4. All visualizations 탭에서 Table 검색·선택.
  5. 쿼리 편집기에서 TraceQL 탭 선택.
  6. Panel options에 트레이스 패널 Title 입력.
  7. 시각화할 트레이스를 검색하는 적절한 TraceQL 쿼리 추가. 고정 쿼리 또는 다른 대시보드 변수를 활용하는 템플릿 쿼리로 작성 가능.
  8. Save 클릭 → 설명 입력 → Save → Back → Exit edit.

쿼리 결과가 반환되면 패널의 테이블에 렌더링됩니다.

변수를 사용해 트레이스에 다른 링크 추가하기

트레이스 시각화 결과에는 트레이스를 렌더링하는 Explore 페이지 링크가 포함됩니다. 선택 시 traceId 대시보드 변수를 채워 같은 대시보드에서 트레이스를 시각화하는 링크를 테이블에 추가할 수 있습니다.

  1. 패널 편집기 메뉴 Data links 아래에서 Add link 클릭.
  2. 데이터 링크 Title 추가.
  3. 브라우저 주소창에서 대시보드의 UUID 확인(같은 인스턴스 대시보드 링크이므로 경로만 필요).
  4. URL 필드에 두 패널이 있는 대시보드에 대한 자기 참조를 만듭니다. 이 참조는 테이블의 선택된 트레이스 값을 사용해 대시보드 변수를 채웁니다. 트레이스 ID는 결과에 traceID 데이터 필드로 노출되므로 이를 변수 값으로 사용.
  5. Save로 데이터 링크 저장 → 설명 입력 → Save → Back → Exit edit.

테이블 시각화에 일치하는 트레이스 목록이 표시됩니다. TraceID·SpanID 필드 선택 시 Explore 페이지를 열거나 데이터 링크를 따라갈 수 있고, 다른 필드(Start time, Name, Duration 등) 선택 시 자동으로 데이터 링크를 따라가 traceId 변수를 채운 뒤 트레이스 패널에 관련 트레이스를 표시합니다.

구성 옵션

패널 옵션 (Panel options)

패널 편집기 창의 Panel options 섹션에서 패널 제목, 설명, 패널 링크 등 기본 옵션을 설정합니다.

Span 필터 옵션 (Span filters options)

Span filters 옵션은 시각화 로드 시 span 필터의 초기 상태를 제어해 트레이스 분석 보기를 커스터마이즈합니다.

옵션 설명
Filters 초기 span 필터 상태를 설정하는 자유 형식 필터 추가. 텍스트 쿼리에는 Text search, duration 필터에는 duration, service.name·span.name 같은 span 속성 사용. 변수 보간 지원. 예: 필터 값을 $var로 설정하면 시각화가 $var 대시보드 변수 값으로 대체.
Show matches only 켜면 정의된 필터 기준과 일치하는 span만 표시. 트레이스 해석 단순화에 도움.
Select critical path 켜면 critical path의 span을 강조해 성능 병목과 전체 지연에 대한 영향을 식별.

Duration 필터는 duration 키를 =, >=, <=, >, < 같은 연산자와 함께 사용합니다. 시각화에서 사용자는 Show all spans를 토글해 필터 보기에서 모든 span으로 전환할 수 있습니다.

더 알아보기 (Learn more)