TraceQL 편집기로 TraceQL 쿼리 작성

TraceQL 편집기로 TraceQL 쿼리 작성 (Write TraceQL queries with the editor)

부모-자식 스팬 간 구조적 쿼리, 집계, 또는 Search 쿼리 빌더가 지원하지 않는 기타 기능이 필요할 때 TraceQL 편집기를 사용하세요. TraceQL 쿼리는 { 조건 } | pipeline 패턴을 따릅니다. PromQL과 LogQL에서 영감을 받은 TraceQL은 트레이스 선택을 위해 설계된 쿼리 언어로, 검색 범위를 제한하므로 쿼리 결과가 더 빠르게 반환돼요.

출처: 문서

본문

시작하려면 편집기에 이 쿼리를 붙여넣고 Run query를 선택하세요:

{ resource.service.name = "frontend" && span:status = error }

이 쿼리는 frontend 서비스의 모든 오류 스팬을 반환해요. frontend를 서비스 이름으로 바꾸세요. 더 많은 예제는 TraceQL query examples 문서를 참고하세요. 쿼리가 결과를 반환하지 않으면 Tempo 데이터 소스가 구성되고 연결됐는지 확인해요.

Grafana Explore의 TraceQL 쿼리 편집기로 트레이스 ID로 검색하고 자동완성을 사용해 TraceQL 쿼리를 작성할 수 있어요.

시작하기 전에

이 기능은 Grafana 10(및 이후)과 Grafana Cloud에서 자동으로 사용할 수 있어요. 자체 호스팅 Grafana 9.3.2 이하에서 TraceQL 쿼리 편집기를 쓰려면 traceqlEditor 기능 토글을 활성화해야 해요.

스트리밍과 gRPC

호스팅 Grafana에서 nginx 같은 게이트웨이 뒤에 있는 자체 관리 Grafana Tempo 또는 Grafana Enterprise Traces 데이터베이스를 쿼리한다면, 그 게이트웨이(예: nginx)가 gRPC 연결을 허용해야 해요. 허용하지 않으면 스트리밍이 동작하지 않고 쿼리가 결과를 반환하지 못해요. gRPC를 허용하도록 게이트웨이를 구성할 수 없다면 호스팅 Grafana에서 스트리밍을 비활성화하세요. Grafana 11.2 이상에서는 Grafana 메인 메뉴의 Connections > Data sources에서 Tempo 데이터 소스 설정의 Streaming 옵션을 비활성화할 수 있어요. 또한 지원 에스컬레이션을 열어 호스팅 Grafana에서 스트리밍 쿼리 결과를 비활성화하도록 요청할 수도 있어요.

쿼리 편집기로 TraceQL 쿼리 작성

  1. Grafana 또는 Grafana Cloud에 로그인해요.
  2. 메인 메뉴에서 Explore를 선택해요.
  3. Tempo 데이터 소스를 선택해요.
  4. TraceQL 탭을 선택해요.
  5. 텍스트 줄에서 {를 입력해 쿼리를 시작해요. TraceQL 문법 도움말은 "Construct a TraceQL query" 문서를 참고하세요.
  6. 선택: Search에서 Copy query를 선택해 빌더 쿼리를 편집기로 전송해요.
  7. 선택: Time picker 드롭다운으로 쿼리 시간과 범위를 변경해요.
  8. 쿼리를 마치면 Run query를 선택해요.

TraceID로 쿼리

  1. 메뉴에서 Explore를 선택하고 원하는 Tempo 데이터 소스를 선택한 뒤 TraceQL 탭으로 이동해요.
  2. 쿼리 필드에 트레이스 ID를 입력해요. 예: 41928b92edf1cdbe0ba6594baee5ae9
  3. Run query를 클릭하거나 키보드 단축키 Shift + Enter를 사용해요.

자동완성으로 쿼리 작성

편집기의 자동완성 제안으로 쿼리를 작성할 수 있어요. 편집기는 spanset을 감지해 관련 자동완성 옵션을 제공해요. 정규식(regex)으로 spanset 내부 위치를 감지해 템포 API에서 속성 이름, 스코프, 내장 이름, 논리 연산자, 또는 속성 값을 제공해요.

고정된 정규식

정규식은 양쪽 끝이 고정(anchored)돼요. 이 고정은 쿼리를 더 빠르게 하고, 정규식도 완전히 고정되는 PromQL의 동작과 일치해요. 고정되지 않은 쿼리(예: { span.foo =~ "bar" })는 이제 { span.foo =~ "^bar$" }로 처리돼요. Grafana 대시보드에서 정규식과 함께 TraceQL을 쓰고 고정되지 않은 동작을 원한다면 { span.foo =~ ".*bar.*"} 같은 고정되지 않은 버전으로 쿼리를 업데이트하세요.

자동완성으로 쿼리 만들기

  1. 메뉴에서 Explore를 선택하고 Tempo 데이터 소스를 선택한 뒤 TraceQL 탭으로 이동해요.
  2. 쿼리를 입력해요. 입력할 때 자동완성 제안이 드롭다운으로 나타나며, 각 글자가 옵션을 좁혀요.
  3. 마우스나 화살표 키로 옵션을 선택하고 Tab을 눌러 쿼리에 추가해요.
  4. 쿼리가 완성되면 Run query를 선택해요.

쿼리 결과 보기

쿼리 결과는 쿼리 편집기 아래의 Table - Traces 같은 테이블에 나타나요. 쿼리 조건과 일치하는 각 스팬(및 그 트레이스)이 반환돼요. 필터 조건이 없으면 모든 스팬이 일치해 관련 트레이스와 함께 반환돼요. 쿼리는 정의된 시간 간격(상대적: 지난 3시간, 또는 절대적)에 대해 수행되며, 응답은 트레이스 수(Limit)와 spanset당 스팬 수(Span Limit)로 제한돼요.

반환된 결과에서 트레이스 ID를 선택하면 트레이스 다이어그램이 열려요. 스팬을 선택하면 트레이스 다이어그램이 열리고 관련 스팬이 강조돼요.

많은 스팬이 있는 spanset을 쿼리하면 성능에 영향을 줄 수 있어요. TraceQL 쿼리 편집기의 Options 섹션에 있는 Span Limit 필드를 사용할 수 있어요. 이 필드는 각 span set에 대해 반환할 최대 스팬 수를 설정해요. 기본적으로 Span Limit 값(또는 spss 쿼리)에 설정할 수 있는 최대값은 100이에요. Tempo 구성에서 이 값은 max_spans_per_span_set 파라미터로 제어되며 Tempo 관리자가 수정할 수 있어요. 기본값보다 높은 값을 입력하면 오류가 발생해요.

Note: max_spans_per_span_set 값을 바꾸는 것은 Grafana Cloud에서 지원되지 않아요.

트레이스 또는 스팬에 초점

Options에서 테이블을 Traces 또는 Spans 초점으로 표시하도록 선택할 수 있어요. Table Type이 Spans로 설정되면 트레이스와 spanset이 스팬 목록으로 펼쳐져요. 각 스팬의 행에 트레이스 서비스와 트레이스 이름이 추가돼 컨텍스트를 더해요. Spans 옵션을 사용하면 변환을 적용하고 대시보드에 표시하기 위해 스팬에 접근하기 쉬워져요.

결과 스트리밍

Tempo 데이터 소스는 TraceQL 쿼리에 대한 스트리밍 응답을 지원해서 전체 쿼리가 끝날 때까지 기다리지 않고 부분 결과를 볼 수 있어요. 스트리밍은 Search와 TraceQL 쿼리 타입 모두에서 사용 가능하며, 결과 테이블에서 들어오는 트레이스를 즉시 볼 수 있어요. 스트리밍 활성화 방법은 Tempo 데이터 소스 문서의 "Streaming"을 참고하세요.

다음 단계

더 알아보기 (Learn more)