TraceQL 쿼리 예시

TraceQL 쿼리 예시 (TraceQL query examples)

이 문서의 TraceQL 쿼리들을 Grafana Explore에서 Tempo 데이터 소스와 함께 사용할 수 있어요. 서비스 이름, 경로, 속성 값을 환경에 맞게 조정하세요. 예시들은 OpenTelemetry semantic conventions를 사용하며, 계측이 다른 속성 이름을 쓴다면 쿼리에서 대체하면 됩니다.

출처: TraceQL query examples

본문

전체 TraceQL 문법은 Construct a TraceQL query를, 확장 레시피 모음은 TraceQL cookbook for Grafana Cloud Traces를 참고하세요.

팁: 쿼리가 결과를 반환하지 않으면 시간 범위를 넓히고 올바른 Tempo 데이터 소스가 선택되었는지 확인하세요. 더 빠른 쿼리를 위해 trace:duration과 trace:rootService 같은 trace 레벨 고유(intrinsic) 필드를 선호하세요.

오류 스팬 찾기 (Find error spans)

오류 상태 또는 HTTP 오류 코드로 필터링:

{ status = error }

{ span.http.status_code >= 500 }

{ span.http.status_code > 399 }

느린 요청 찾기 (Find slow requests)

스팬 기간으로 필터링. 일반적인 임계값은 1초와 5초예요.

{ duration > 1s }

{ duration > 5s }

특정 엔드포인트를 기간으로 필터링:

{ span.http.url = "/api/checkout" && duration > 2s }

유형별 예외 찾기 (Find exceptions by type)

스팬에 기록된 예외 이벤트를 쿼리해요. OpenTelemetry는 예외를 스팬 이벤트로 기록하므로 예외 데이터는 event 스코프를 사용해요.

{ event.exception.message =~ "context cancelled" }

{ event.exception.type = "NotFoundException" }

예외 메시지가 있는 오류 스팬 찾기:

{ status = error && event.exception.message != "" }

서비스로 필터링 (Filter by service)

특정 서비스의 스팬을 선택하거나 패턴으로 서비스를 매칭해요. Service Graph view를 사용해 높은 오류율이나 지연이 있는 서비스를 식별한 뒤 TraceQL로 그 서비스를 쿼리할 수 있어요.

{ resource.service.name = "checkout" }

{ resource.service.name =~ "payment.*" && status = error }

오류와 느린 스팬 함께 찾기

오류 상태와 기간 필터를 결합해 가능한 근본 원인을 식별:

{ resource.service.name = "api" && status = error && duration > 1s }

서비스 의존성 분석 (Analyze service dependencies)

특정 API 경로에서 오류 찾기:

{ span.http.url =~ ".*/api/.*" && span.http.status_code >= 500 }

후손(downstream) 연산자(>>)를 사용해 프론트엔드 서비스가 오류를 내는 하류 서비스를 호출하는 트레이스를 찾아요.

{ resource.service.name = "frontend" } >> { resource.service.name = "database" && status = error }

rate 및 count 메트릭 쿼리 (Query rate and count metrics)

Explore의 Metrics 모드에서 실행해요. TraceQL 메트릭 쿼리는 기본 24시간 시간 범위 제한이 있어요.

{ } | rate()

{ status = error } | rate()

{ resource.service.name = "api" } | count_over_time()

{ duration > 1s } | rate()

지역 또는 환경으로 필터링 (Filter by region or environment)

특정 클라우드 지역 또는 배포 환경으로 범위를 좁혀요.

{ resource.cloud.region = "us-east-1" && status = error }

{ resource.deployment.environment = "production" && duration > 2s }

대시보드 변수 사용 (Use dashboard variables)

패널에서 이 쿼리들을 사용할 때 하드코딩된 값을 대시보드 변수로 바꾸세요. 예를 들어 $service 변수를 사용하면:

{ resource.service.name = "$service" && status = error }

추가 자료 (More resources)

TraceQL cookbook for Grafana Cloud Traces — 추가 예시가 있는 확장 레시피 모음
Construct a TraceQL query — 전체 TraceQL 문법, 스코프, 연산자
Query tracing data — 쿼리 편집기 모드와 옵션
Service Graph and Service Graph view — 서비스 의존성 시각화

TraceQL 쿼리 예시