트레이싱 데이터 쿼리하기
트레이싱 데이터 쿼리하기 (Query tracing data)
Tempo 데이터 소스의 쿼리 편집기로 Explore에서 Tempo의 트레이스를 쿼리·표시할 수 있어요. 쿼리는 트레이싱을 위해 특별히 설계된 쿼리 언어인 TraceQL을 사용합니다. 검색 빌더, TraceQL 편집기, Service Graph 뷰 세 가지 모드를 제공해요.
팁: TraceQL을 모르시나요? RED 메트릭으로 트레이싱 데이터를 탐색하는 직관적·쿼리 없는 앱인 Grafana Traces Drilldown을 써 보세요.
출처: 문서
본문
시작하기 전에
Explore와 Tempo 데이터 소스로 Grafana·Grafana Cloud에서 TraceQL 쿼리를 작성할 수 있어요.
참고: 쿼리 실행 전 Tempo 데이터 소스가 구성·연결되었는지 확인하세요. 결과가 없거나 오류가 나면 Tempo 데이터 소스 구성에서 연결·인증을 확인하세요.
TraceQL을 몰라도 쿼리를 만들 수 있어요. Search 쿼리 빌더로 드롭다운에서 옵션을 선택해 시각적으로 쿼리를 만들고, 생성된 TraceQL 쿼리를 TraceQL 편집기로 옮겨 더 다듬을 수 있어요.
TraceQL 쿼리는 { conditions } | pipeline 패턴을 따릅니다. {} 안의 조건이 스팬을 선택하고 count()·avg() 같은 파이프라인 연산자가 결과를 집계해요. 전체 문법은 TraceQL 쿼리 구성, 언어 개요는 TraceQL 문서를 참고하세요.
쿼리 편집 모드 선택
쿼리 편집기에는 세 가지 Query types가 있어요.
Search 쿼리 빌더
데이터를 탐색하거나 TraceQL을 배우는 데 시작하기 좋아요. 드롭다운·텍스트 필드로 TraceQL 문법을 몰라도 시각적으로 쿼리를 만듭니다. 선택이 자동으로 TraceQL 쿼리를 생성하며 편집기로 복사해 더 다듬을 수 있어요. 자세한 내용은 쿼리 빌더로 트레이스 검색을 참고하세요.
TraceQL 쿼리 편집기
Search 빌더가 지원하지 않는 복잡한 필터, 부모·자식 스팬 간 구조적 쿼리, 집계가 필요할 때 사용해요. 속성 이름·범위·연산자 자동완성을 제공하며 쿼리 필드에 트레이스 ID를 직접 입력해 검색할 수도 있어요. 복사·붙여넣기 예시는 TraceQL 쿼리 예시, 편집기 사용법은 편집기로 TraceQL 쿼리 작성을 참고하세요.
Service graph 뷰
개별 트레이스를 찾는 대신 서비스가 어떻게 연결되는지 시각화하고 연결 전반의 요청률·오류율·기간(RED 메트릭)을 강조해요. 다음을 할 수 있습니다.
- 일관되게 오류를 반환하는 스팬과 그 발생률 발견
- 서비스 전반의 스팬 호출 전반적 비율 개요
- 서비스에서 가장 느린 쿼리 완료 시간 확인
- rate·error·duration 값(RED 신호)을 기준으로 특정 관심 스팬을 포함한 모든 트레이스 검토
Service Graph는 메트릭 생성이 구성되어 있어야 해요. 자세한 내용은 Service Graph 뷰를 참고하세요.
검색 동작 이해
Tempo 검색은 비결정적(non-deterministic)이에요. 검색 시 Tempo가 선택된 시간 범위에서 대규모 병렬 스캔을 수행하고 처음 N개의 일치 결과를 반환합니다. 기계 부하·네트워크 지연 때문에 같은 검색도 다른 결과를 줄 수 있어요. 이 설계는 예측 가능성보다 속도를 우선합니다. 결정적 결과를 원하면 TraceQL 쿼리에 with 절을 붙이세요. 예: { status = error } with (most_recent=true). 자세한 내용은 최근 결과 검색 참고.
대시보드에 TraceQL 패널 사용
TraceQL 패널 추가는 Traces 패널 문서를, Grafana 대시보드는 Use dashboards를 참고하세요. 예제 대시보드는 Grafana Play에서 확인.
쿼리 빌더·편집기 옵션 설정
Search와 TraceQL 쿼리 유형의 옵션은 Options 섹션에서 수정할 수 있어요. 옵션 변경 후 쿼리를 다시 실행해 업데이트를 적용하세요.
쿼리 유형 함께 사용
+ Add query로 쿼리 유형을 하나 이상 조합한 커스텀 쿼리를 만들 수 있어요. 새 쿼리를 추가할 때마다 Search, TraceQL, 또는 Service Graph UI를 포함하는 새 섹션(쿼리 블록)이 추가됩니다. 추가된 쿼리·결과 테이블은 내비게이션의 Queries·Tables 아래에 나타나요.
- 쿼리 블록 추가: + Add query → 쿼리 유형 선택
- 블록 제거: Remove query 휴지통 아이콘
- 블록 이름 변경: 블록 이름 옆 Rename 편집 아이콘
각 쿼리 블록에는 오른쪽 상단에 아이콘 세트(추가 옵션 툴바)가 있어요.
쿼리 기록과 쿼리 검사기 사용
Explore는 데이터 소스에서 사용한 모든 쿼리 기록과 통계·쿼리 검사·JSON 보기 등을 제공하는 검사기를 써요. Explore 검사기·Explore 쿼리 관리를 참고하세요.
JSON 트레이스 파일 업로드
단일 트레이스를 담은 JSON 파일을 업로드해 시각화할 수 있어요(여러 트레이스면 첫 번째만 시각화). Explore에서 쿼리 유형 선택기 옆 Import trace를 선택해 업로드하세요. Inspector 패널로 트레이스·서비스 그래프를 다운로드하려면 데이터 탭에서 Download traces/Download Service Graph 클릭.
교차 테넌트 TraceQL 쿼리
멀티 스택 Tempo 데이터 소스를 구성했다면 스택·테넌트에 걸쳐 TraceQL 쿼리를 수행할 수 있어요. X-Scope-OrgID 헤더에서 지정한 모든 테넌트에 걸쳐 수행됩니다. 여러 스팬셋을 비교하는 TraceQL 쿼리는 교차 테넌트 쿼리에서 모든 트레이스를 올바르게 반환하지 못할 수 있어요. 예:
{ span.attr1 = "bar" } && { span.attr2 = "foo" }
TraceQL은 연속 저장된 트레이스를 평가합니다. 두 조건이 서로 다른 테넌트에 만족되면 Tempo는 트레이스를 반환하지 않아요. 구성은 멀티 스택 Tempo 데이터 소스, Tempo 구성 요구사항은 교차 테넌트 쿼리·멀티테넌시를 참고하세요.