Cloud Trace 필터

Cloud Trace 필터를 사용하면 Trace API list 메서드를 쿼리하여 스팬 이름, 최소 지연 시간, HTTP 속성, 라벨과 같은 특정 기준과 일치하는 trace만 검색할 수 있습니다.

이러한 필터 표현식은 Google Cloud 콘솔의 Trace 탐색기 페이지에는 적용되지 않습니다. Trace 탐색기에서 스팬 필터 창의 사전 정의된 필터를 사용하거나 필터 표시줄을 사용하여 트레이스를 필터링할 수 있습니다. 자세한 내용은 trace 찾기 및 탐색을 참고하세요.

필터 개요

추적 필터는 조건(Terms)이라고 부르는 비교 시퀀스로 구성됩니다. 추적은 선택할 필터의 모든 조건과 일치해야 합니다. 예를 들어 다음 필터는 지연 시간이 1초 이상이고 /modules.GetNumInstances라는 스팬이 포함된 트레이스와 일치합니다.

+span:/modules.GetNumInstances latency:1s

모든 문자열 비교는 대소문자를 구분합니다.

부울 속성

불리언 속성의 값을 지정하려면 false의 경우 false을, true의 경우 true을 사용하세요.

Client:true

특수문자

[a-zA-Z0-9./_][a-zA-Z0-9./_-]* 정규 표현식과 일치하는 단순 값은 따옴표 없이 제공할 수 있습니다.

environment:production
path:/index.html
error_code:200

공백을 포함한 다른 문자가 포함된 값은 큰따옴표 (") 문자로 묶어야 합니다.

my-label:"Notice: This value contains spaces and a colon"

따옴표로 묶은 문자열 내에서 큰따옴표 문자 또는 백슬래시(\) 문자를 검색하려면 백슬래시로 문자를 이스케이프 처리하세요.

my-label:"Notice: This value contains spaces, a colon, a \"quote\", and a backslash (\\)"

필터 구문

이 페이지에서 NAME은 필드의 이름을 나타내고 VALUE은 키-값 쌍의 값을 나타냅니다. _PREFIX 및 _EXACT 문자열은 테스트가 접두사 테스트인지 정확한 일치인지 시각적으로 나타냅니다. 예를 들어 root:[NAME_PREFIX]는 루트 스팬의 이름이 [NAME_PREFIX]로 시작해야 함을 의미합니다.

이 페이지의 나머지 부분에서는 Trace API의 필터 구문을 설명합니다.

요청 필터 예시

다음 목록은 필터 조건을 설명합니다.

root:[NAME_PREFIX]

추적의 루트 스팬 이름은 [NAME_PREFIX]로 시작되어야 합니다. 예를 들어 다음 필터는 "/_ah/background"라는 trace와 일치하지만 "/_ahx/background"라는 trace와는 일치하지 않습니다.

root:/_ah/
+root:[NAME]

추적의 루트 스팬 이름은 정확히 [NAME]이어야 합니다. 예를 들면 다음과 같습니다.

+root:/_ah/background
[NAME_PREFIX]

이 문법은 root:[NAME_PREFIX]의 단축키입니다.

+[NAME]

이 문법은 +root:[NAME]의 단축키입니다.

span:[NAME_PREFIX]

추적에 이름이 [NAME_PREFIX]로 시작되는 스팬이 최소한 한 개 이상 있어야 합니다. 예를 들면 다음과 같습니다.

span:/modules.
+span:[NAME]

추적에 이름이 정확히 [NAME]인 스팬이 최소한 한 개 이상 있어야 합니다. 예를 들면 다음과 같습니다.

+span:/modules.GetNumInstances
latency:[DURATION]

트레이스의 전체 지연 시간이 [DURATION] 이상이어야 합니다. 기간은 정수 뒤에 단위 지정자(초는 s, 밀리초는 ms, 나노초는 ns)로 표현됩니다. 단위 지정자가 없으면 단위는 밀리초입니다. 예를 들어 다음 네 가지 기간은 동일합니다.

12s 12000ms 12000000ns 12000
label:[LABEL_KEY]

추적에 정확히 지정된 라벨 키가 있어야 합니다. 라벨 값(있는 경우)은 중요하지 않습니다. 예를 들면 다음과 같습니다.

label:/http/url
[LABEL_KEY]:[VALUE_PREFIX]

추적에 정확히 지정된 라벨 키가 있어야 하며, 라벨 값이 [VALUE_PREFIX]로 시작되어야 합니다. 예를 들어 다음 용어는 App Engine 버전이 "2017"로 시작하는 트레이스와 일치합니다.

g.co/gae/app/module_version:2017
+[LABEL_KEY]:[VALUE_EXACT]

추적에 정확히 지정된 라벨 키와 값이 있어야 합니다. 예를 들면 다음과 같습니다.

+g.co/gae/app/module_version:201750925t173233.387410594824284458
method:[VALUE_PREFIX]

이 문법은 라벨 테스트 /http/method:[VALUE_PREFIX]의 바로가기입니다.

+method:[VALUE_EXACT]

이 문법은 라벨 테스트 +/http/method:[VALUE_EXACT]의 바로가기입니다.

url:[VALUE_PREFIX]

이 문법은 라벨 테스트 /http/url:[VALUE_PREFIX]의 바로가기입니다.

+url:[VALUE_EXACT]

이 문법은 라벨 테스트 +/http/url:[VALUE_EXACT]의 바로가기입니다.

루트 스팬 검색의 예시

검색어를 루트 스팬으로만 제한하려면 검색어 앞과 선택적인 더하기 기호 (+) 뒤에 캐럿 (^)을 추가합니다. trace 탐색기 페이지의 필터 필드에 대해 +^ 주석을 추가하면 Enter를 누를 때 ^+로 변환됩니다.

다음은 루트 스팬에만 제한되는 검색 조건의 예와 그 의미입니다.

^label:[LABEL_KEY]
label:[LABEL_KEY]의 루트 스팬 검색입니다.
^[LABEL_KEY]:[VALUE_PREFIX]
[LABEL_KEY]:[VALUE_PREFIX]의 루트 스팬 검색입니다.
+^[LABEL_KEY]:[VALUE]
+[LABEL_KEY]:[VALUE]의 루트 스팬 검색입니다.
^method:[VALUE_PREFIX]
method:[VALUE_PREFIX]의 루트 스팬 검색입니다.
+^method:[VALUE]
+method:[VALUE]의 루트 스팬 검색입니다.
^url:[VALUE_PREFIX]
url:[VALUE_PREFIX]의 루트 스팬 검색입니다.
+^url:[VALUE]
+url:[VALUE]의 루트 스팬 검색입니다.
^span:[NAME_PREFIX]
root:[NAME_PREFIX]와 동일합니다.
+^span:[NAME]
+root:[NAME]와 동일합니다.

혼합된 용어로 쿼리를 만들어 검색을 추가로 맞춤설정할 수 있습니다. 예를 들면 다음과 같습니다.

+^url:/main /images method:200

이 쿼리는 루트 스팬 라벨 /http/url이 정확히 '/main'이고, 루트 스팬의 이름에 /images 프리픽스가 붙고, 모든 스팬의 /http/method가 200의 값을 가지는 trace와 일치합니다.

문제 해결

다음 섹션에서는 트레이스 필터의 일반적인 문제를 해결하는 방법을 설명합니다.

느린 성능

추적 필터가 복잡하면 실행하는 데 시간이 오래 걸리고 시간 초과될 수 있습니다. 성능을 향상시키려면 필터를 간소화합니다.

결과 없음

필터가 트레이스를 반환하지 않으면 다음을 확인하세요.

  • 비교 조건을 구분하는 필터를 제외하고는 필터에 공백이 없어야 합니다.

  • 필터에 있는 모든 단어의 대소문자와 철자가 올바른지 확인하세요. 예를 들어 method:GET와 같은 키워드의 철자를 잘못 입력하면 필터가 label:method:GET로 해석되어 어떤 트레이스도 일치하지 않습니다.

  • 필터 용어를 한 번에 하나씩 테스트하려면 list API 메서드로 이동한 다음 API 탐색기를 사용하세요. 용어 중 하나가 결과를 반환하지 않으면 해당 용어가 데이터가 반환되지 않는 이유일 수 있습니다.

    페이지에 이 메서드 사용해 보기라는 제목의 창이 표시되면 API 탐색기가 열립니다. 필요한 경우 사용해 보기를 클릭하여 API 탐색기를 엽니다.