Cloud Trace 필터

trace 필터를 사용하여 Cloud Trace에서 trace 집합을 선택합니다. 다음 방법 중 하나를 사용하여 추적 필터를 사용하세요.

list API 메서드를 사용하여 쿼리의 필터 매개변수로 사용.
분석 보고서를 만들 때 요청 필터 매개변수로 사용.
trace 탐색기 페이지에서 필터 필드로 사용. 이러한 필터를 만들고 수정하는 방법은 최근 trace 표시를 참조하세요.

참고: trace 탐색기 페이지의 필터 막대는 메뉴로 구동되며 구성에 따라 옵션이 달라집니다. 메뉴 구동 옵션에는 일반적으로 HTTP 상태 및 HTTP 메서드별 필터링이 포함됩니다. App Engine을 사용할 때는 서비스 및 버전 옵션도 사용할 수 있습니다. Cloud Trace 필터를 사용할 때는 이러한 옵션을 사용할 수 없습니다.

필터를 사용하면 trace가 표시되어야 하는 조건을 하나 이상 지정할 수 있습니다. 필터 구문을 사용하면 일치 항목이 언제 정확한지 또는 언제 프리픽스 테스트인지를 정의할 수 있습니다. 모든 일치 항목은 대소문자를 구분합니다.

필터 개요

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

+span:/modules.GetNumInstances latency:1s

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

불리언 속성

불리언 속성의 값을 지정하려면 false의 경우 0을, true의 경우 1을 사용하세요. 예를 들면 다음과 같습니다.

Client:0

특수문자

공백이나 콜론(:) 문자가 포함된 값을 검색하려면 값을 큰따옴표(")로 묶습니다. 예를 들면 다음과 같습니다.

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

따옴표로 묶인 문자열에서 큰따옴표 문자 또는 백슬래시(\) 문자를 검색하려면 백슬래시로 문자를 이스케이프합니다. 예를 들면 다음과 같습니다.

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

필터 구문

다음 표 및 이 페이지에서 NAME은 필드 이름을 나타내고 VALUE는 키-값 쌍의 값을 나타냅니다. _PREFIX 및 _EXACT 문자열은 테스트가 프리픽스 테스트인지, 일치검색인지 나타냅니다. 예를 들어 root:[NAME_PREFIX]는 루트 스팬의 이름이 [NAME_PREFIX]로 시작해야 함을 의미합니다.

다음 표에는 Cloud Trace에서 사용되는 필터 구문이 나와 있습니다.

분석 보고서 페이지의 Trace API 요청 필터	trace 탐색기 페이지의 필터
`root:[NAME_PREFIX]`	`RootSpan:[NAME_PREFIX]`
`+root:[NAME_EXACT]`	`RootSpan:+[NAME_EXACT]`
`span:[NAME_PREFIX]`	`SpanName:[NAME_PREFIX]`
`+span:[NAME_EXACT]`	`SpanName:+[NAME_EXACT]`
`[NAME_PREFIX]`	`RootSpan:[NAME_PREFIX]`
`label:[LABEL_KEY]`	`HasLabel:[LABEL_KEY]`
`[LABEL_KEY]: [VALUE_PREFIX]`	`[LABEL_KEY]:[VALUE_PREFIX]`^*
`+[LABEL_KEY]: [VALUE_EXACT]`	`[LABEL_KEY]:+[VALUE]`^*
`^[LABEL_KEY]: [VALUE_PREFIX]`	`[LABEL_KEY]:^[VALUE_PREFIX]`^*
`+^[LABEL_KEY]: [VALUE_EXACT]`	`[LABEL_KEY]:^+[VALUE_EXACT]`^{*, †}
`method:[VALUE_PREFIX]`	`Method:[VALUE_PREFIX]`
`latency:10ms`	`MinLatency:10ms`
`url:[VALUE_PREFIX]`	`URL:[VALUE_PREFIX]`

^* root, span, label, method, latency, url Trace 키워드를 라벨 키로 사용하지 마세요. 이러한 라벨 키가 포함된 trace는 쿼리할 수 없습니다.
^† trace 탐색기 페이지에서 Enter를 누르면 +^ 주석이 ^+로 변환됩니다.

이 페이지의 나머지 부분에서는 Trace API를 사용할 때 필터 및 분석 보고서 페이지의 요청 필터에 대해 설명합니다. trace 탐색기 페이지에서 필터 필드를 사용하는 경우 이전 테이블의 매핑을 사용해서 상응하는 표현식을 만들 수 있습니다.

요청 필터 예시

다음은 필터 조건에 대한 설명입니다.

root:[NAME_PREFIX]

trace의 루트 스팬 이름은 [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"로 시작하는 trace와 일치합니다.

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와 일치합니다.

문제 해결

이 섹션에는 문제 해결 콘텐츠가 포함되어 있습니다.

느린 성능

trace 필터가 복잡하면 실행하는 데 시간이 오래 걸려 타임아웃될 수 있습니다. 성능을 향상시키려면 필터를 간소화합니다.

결과 없음

필터가 추적을 반환하지 않으면 다음을 확인하세요.

비교 조건을 구분하는 필터를 제외하고는 필터에 공백이 없어야 합니다.
필터의 모든 단어의 대소문자와 철자가 올바른지 확인합니다. 예를 들어 method:GET과 같은 키워드의 철자를 잘못 입력하면 필터가 label:method:GET로 해석되어 어떠한 trace와도 일치하지 않습니다.
필터 조건을 한 번에 하나씩 테스트하려면 trace 목록 필터 또는 API 탐색기를 사용합니다. 조건 중 하나가 결과를 반환하지 않는다면 그 조건이 원인일 수 있습니다.