쿼리 빌더로 트레이스 검색하기
쿼리 빌더로 트레이스 검색하기 (Search traces using the query builder)
Search 쿼리 빌더는 문법을 직접 쓰는 대신 드롭다운·텍스트 필드로 TraceQL 쿼리를 만들 수 있게 해줘요. 선택할 때마다 뒤에서 TraceQL 쿼리가 생성되고, 언제든 생성된 쿼리를 보고 TraceQL 편집기로 복사할 수 있어요. 데이터를 탐색하거나 TraceQL 패턴을 배울 때 사용하세요.
출처: 문서
본문
구조적 연산자·집계를 포함한 복잡한 쿼리는 TraceQL 편집기를, 전체 쿼리 문법은 TraceQL 쿼리 구성을 참고하세요. 쿼리가 결과를 반환하지 않으면 Tempo 데이터 소스 구성·연결을 확인하세요.
Search 빌더 활성화
이 기능은 Grafana 10(및 이후)·Grafana Cloud에서 자동 사용 가능해요. 자체 관리 Grafana 10.1까지는 traceqlSearch 기능 토글을 활성화하세요.
Search로 TraceQL 쿼리 작성
Search 쿼리 빌더는 Grafana의 Explore > Query type > Search에 있으며, 선택이 자동으로 TraceQL 쿼리를 생성합니다. 빌더는 가장 흔한 쿼리를 최소 클릭으로 실행하게 하며, 구조적 연산자(>>, >, =~, !=) 등 TraceQL 기능의 하위 집합을 지원해요. 리소스 서비스 이름, 스팬 이름, 기간, 하나 이상의 태그로 트레이스를 검색할 수 있고, 빌더 블록 추가·쿼리 기록·Inspector도 사용할 수 있어요.
검색 수행
검색을 하려면 필터를 선택하고 쿼리를 실행하세요. 결과는 쿼리 빌더 아래에 나타납니다.
| 번호 | 이름 | 동작 |
|---|---|---|
| 1 | Data source | 데이터 소스 드롭다운에서 Tempo 데이터 소스 선택 |
| 2 | Query type | Search 선택 |
| 3 | Choose filter | 필터 하나 이상 선택. 선택 사항 — 빈 쿼리도 가능(TraceQL에서 {}는 유효한 쿼리이며 모든 트레이스/스팬 목록 제공) |
| 4 | Filters conditions | 하나 이상 필터의 옵션 선택. 예: Service Name(resource.service.name)이 =(equal) user인 필터 정의. 선택 사항 — 최소 하나의 태그·필터 필요 |
| 5 | Tags and Aggregate by | 스팬·리소스·unscoped 태그 추가·조건 정의. Aggregate by로 결과 그룹화. 선택 사항 |
| 6 | TraceQL query | 선택으로 구성된 TraceQL 쿼리 표시. Run query 시 실행 |
모든 쿼리는 선택한 시간 범위의 데이터를 검색해요. 기본적으로 지난 한 시간입니다. Run query 왼쪽의 Time range로 변경하세요.
Search 빌더 접근: Grafana 로그인 → Tempo 데이터 소스 선택 → Explore → Query type > Search.
필터 정의
필터로 Service Name, Span Name, Status, Duration을 선택해 반환 데이터를 세밀화해요. Duration은 스팬의 종료-시작 시간으로 계산된 스팬 시간입니다. 관리자는 Tempo 데이터 소스 구성으로 기본 필터를 변경할 수 있고, 필드 유형이 사용 가능한 연산자를 결정해요. 문자열 필드(Span/Service Name)는 =, !=, =~, !~, Duration 필드는 범위 선택(>, >=, <, <=)을 사용합니다.
같은 필터에 여러 값을 선택할 수 있어요. 생성 쿼리는 연산자에 따라 달라집니다.
=나 비정규식 연산자: 각 값이 괄호 안에서||로 연결된 별도 조건(!=는&&로 연결)=~/!~: 값들이 단일 따옴표 문자열 안에서|로 연결
예: Span Name에 = 연산자로 get·log_results_cache 선택 시:
{ name="get" || name="log_results_cache" }
정규식 =~ 사용 시:
{ name=~"get|log_results_cache" }
필터 정의 단계: 필터 선택 → 비교 연산자 선택 → Service/Span Name/Status: 값 선택, Duration: 범위·단위(ns,ms,s,m,h)와 연산자 입력 → Run query.
태그 정의
스팬(scoped)·리소스·unscoped 태그를 추가해 결과를 더 필터링할 수 있어요. unscoped를 선택하면 모든 태그에서 일치를 검색합니다. 단계: span/resource/unscoped 선택 → Select tag 드롭다운에서 태그 선택 → 비교 연산자 선택 → Select value에서 값 선택 → (선택) **+**로 태그 추가.
(선택) Aggregate by 사용
경고: Metrics summary API와 Aggregate by 기능은 Grafana Cloud와 Grafana 11.3 이상에서 더 이상 사용되지 않으며(디프리케이트), 향후 릴리스에서 제거될 예정입니다.
Aggregate by로 필터 기준에 맞는 kind=server 스팬의 RED 메트릭(전체 스팬 수, 오류 스팬 비율, 지연 정보)을 하나 이상의 속성으로 그룹화해 계산할 수 있어요. 이 기능은 metrics summary API를 기반으로 하며, 지난 한 시간 내 수신된 스팬의 요약만 계산해요. 기본 비활성화이며 metricsSummary 기능 토글을 활성화해야 합니다. Tempo 데이터 소스는 Metrics Summary API가 활성화된 Tempo 데이터베이스를 가리켜야 해요.
사용 방법: Aggregate by 행에서 첫 드롭다운으로 scope(예: span) 선택 → 두 번째 드롭다운에서 속성 선택 → (선택) **+**로 행 추가 → (선택) Time range 조정 → Run query. 각 집계 값(예: intrinsic:name)이 결과 테이블에 컬럼으로 대응합니다.
(선택) 쿼리·서비스 그래프 블록 추가
Add query로 순차 실행되는 연속 쿼리·서비스 노드 블록을 가질 수 있어요. 드래그 앤 드롭으로 순서를 바꿀 수 있습니다. 자세한 내용은 쿼리 유형 함께 사용 참고.
쿼리 실행과 결과 보기
Run query로 TraceQL 쿼리를 실행하세요. 결과는 쿼리 빌더 아래 테이블에 나타나고, Trace ID 선택으로 상세 정보를 표시합니다. Span Filters로 쿼리 결과를 더 세밀화할 수 있어요.
결과 스트리밍
Tempo 데이터 소스는 TraceQL 쿼리에 스트리밍 응답을 지원해 전체 쿼리가 끝나기 전에 부분 결과를 볼 수 있어요. 활성화 시 모든 구성된 Tempo 데이터 소스가 스트리밍을 시도하며, 데이터 소스 단위로 Streaming 섹션에서 제어할 수 있어요. Search와 TraceQL 모두에서 사용 가능합니다.
스팬의 필터·태그 사용
Span Filters로 트레이스 상세 보기에서 결과를 세밀화할 수 있어요. Service Name, Span Name, Duration, Tags는 Search 빌더의 같은 이름 필터와 기능·동작이 동일합니다. 키워드 검색, Show matches only, Show critical path only, Prev/Next 탐색도 가능하며 Clear로 필터를 초기화해요.
흔한 검색 시도
서비스의 오류 스팬 찾기: Service Name frontend, Status error →
{ resource.service.name = "frontend" && status = error }
느린 API 호출 찾기: Span Name POST /api/orders, Duration > 500ms →
{ name = "POST /api/orders" && duration > 500ms }
HTTP 상태 코드로 필터링: 태그 추가로 span·http.response.status_code 선택, 연산자 >=, 값 500 →
{ span.http.response.status_code >= 500 }