trace 탐색기 페이지에서 필터filter_list 필드로 사용. 이러한 필터를 만들고 수정하는 방법은 최근 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와 일치합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-01-23(UTC)"],[],[],null,["# Cloud Trace filters\n\nThis document describes how you can configure filters when you use the\nCloud Trace API [`list`](/trace/docs/reference/v1/rest/v1/projects.traces/list) method.\nFilters let you specify one or more conditions that must be\nsatisfied for a trace to be returned.\n\nThe page doesn't apply to the\n**Trace Explorer** page. To filter the data shown on that page,\neither use the predefined filters, which are listed in the\n**Span filters** pane, or use the **Filter** bar.\nFor more information, see [Find and explore traces](/trace/docs/finding-traces).\n\nFilter overview\n---------------\n\nTrace filters consist of a sequence of\ncomparisons called **terms** . Traces must\nmatch all the terms in the filter to be selected. For example, the following\nfilter matches traces that have a latency of one second or more, and that\ncontain a span named `/modules.GetNumInstances`: \n\n +span:/modules.GetNumInstances latency:1s\n\nAll string comparisons are case-sensitive.\n\n### Boolean attributes\n\nTo specify values for Boolean attributes, use `false` for false, and `true`\nfor true: \n\n Client:true\n\n### Special characters\n\nSimple values, that is those that match the regular expression\n`[a-zA-Z0-9./_][a-zA-Z0-9./_-]*`, can be provided without quotation: \n\n environment:production\n path:/index.html\n error_code:200\n\nValues that include other characters, including whitespace, must be enclosed in\ndouble-quote (`\"`) characters: \n\n my-label:\"Notice: This value contains spaces and a colon\"\n\nTo search for the double-quote character or the backslash\n(`\\`) character within\na quoted string, escape the character with a backslash: \n\n my-label:\"Notice: This value contains spaces, a colon, a \\\"quote\\\", and a backslash (\\\\)\"\n\nFilter syntax\n-------------\n\nOn this page, `NAME` refers to the name\nof a field while `VALUE` refers to the value of a key-value pair. The strings\n`_PREFIX` and `_EXACT` are visual indications of whether a test is a\nprefix-test or an exact match. For example, `root:[NAME_PREFIX]` means\nthat the name of the root span must begin with `[NAME_PREFIX]`.\n| **Note:** Don't use the following keywords as label keys: `root`, `span`, `label`, `method`, `latency`, and `url`. Traces with these label keys can't be queried.\n\nThe remainder of this page contains a description for filters when using\nCloud Trace API.\n\n### Request filter examples\n\nThe following describes the filter terms:\n\n`root:[NAME_PREFIX]`\n\n: The trace's root-span name must begin with \\[NAME_PREFIX\\]. For example, the\n following filter matches a trace named `\"/_ah/background\"`, but not one\n named `\"/_ahx/background\"`:\n\n root:/_ah/\n\n`+root:[NAME]`\n\n: The trace's root-span name must be \\[NAME\\], exactly. For example:\n\n +root:/_ah/background\n\n`[NAME_PREFIX]`\n\n: This syntax is a shortcut for `root:[NAME_PREFIX]`.\n\n`+[NAME]`\n\n: This syntax is a shortcut for `+root:[NAME]`.\n\n`span:[NAME_PREFIX]`\n\n: The trace must have at least one span whose name begins with \\[NAME_PREFIX\\].\n For example:\n\n span:/modules.\n\n`+span:[NAME]`\n\n: The trace must have at least one span whose name is \\[NAME\\], exactly. For\n example,\n\n span:/modules.GetNumInstances\n\n`latency:[DURATION]`\n\n: The trace must have an overall latency that is greater or equal to\n \\[DURATION\\]. The duration is expressed as an integer followed by a units\n specifier: `s` for seconds, `ms` for milliseconds, or `ns` for nanoseconds.\n If there is no unit specifier, then the units are milliseconds. For\n example, the following four durations are the same:\n\n 12s 12000ms 12000000ns 12000\n\n`label:[LABEL_KEY]`\n\n: The trace must contain the specified label key, exactly. The value of the\n label (if any) doesn't matter. For example,\n\n label:/http/url\n\n`[LABEL_KEY]:[VALUE_PREFIX]`\n\n: The trace must contain the specified label key, exactly, and the value of\n the label must start with \\[VALUE_PREFIX\\]. For example, the following term\n matches traces whose App Engine version begins with `\"2017\"`.\n\n g.co/gae/app/module_version:2017\n\n`+[LABEL_KEY]:[VALUE_EXACT]`\n\n: The trace must contain the specified label key *and* value, exactly.\n For example,\n\n +g.co/gae/app/module_version:201750925t173233.387410594824284458\n\n`method:[VALUE_PREFIX]`\n\n: This syntax is a shortcut for the label test, `/http/method:[VALUE_PREFIX]`.\n\n`+method:[VALUE_EXACT]`\n\n: This syntax is a shortcut for the label test, `+/http/method:[VALUE_EXACT]`.\n\n`url:[VALUE_PREFIX]`\n\n: This syntax is a shortcut for label test, `/http/url:[VALUE_PREFIX]`.\n\n`+url:[VALUE_EXACT]`\n\n: This syntax is a shortcut for label test, `+/http/url:[VALUE_EXACT]`.\n\n### Root-span search examples\n\nTo restrict the search term to only the root span, add a (`^`) before a\nsearch term and after the optional (`+`).\nFor the **Filter** field in the **Trace Explorer** page, if you add the\nannotation `+^`, it is converted to `^+` when you press **Enter**.\n\nThe following show some root-span-only search terms and their equivalences:\n\n`^label:[LABEL_KEY]`\n: This is a root-span search for `label:[LABEL_KEY]`.\n\n`^[LABEL_KEY]:[VALUE_PREFIX]`\n: This is a root-span search for `[LABEL_KEY]:[VALUE_PREFIX]`.\n\n`+^[LABEL_KEY]:[VALUE]`\n: This is a root-span search for `+[LABEL_KEY]:[VALUE]`.\n\n`^method:[VALUE_PREFIX]`\n: This is a root-span search for `method:[VALUE_PREFIX]`.\n\n`+^method:[VALUE]`\n: This is a root-span search for `+method:[VALUE]`.\n\n`^url:[VALUE_PREFIX]`\n: This is a root-span search for `url:[VALUE_PREFIX]`.\n\n`+^url:[VALUE]`\n: This is a root-span search for `+url:[VALUE]`.\n\n`^span:[NAME_PREFIX]`\n: This is equivalent to `root:[NAME_PREFIX]`.\n\n`+^span:[NAME]`\n: This is equivalent to `+root:[NAME]`.\n\nBy creating a query with mixed terms, the search can be further customized.\nFor example, \n\n +^url:/main /images method:200\n\nmatches traces when the root span label `/http/url` is exactly \"/main\",\nthe root span's name is prefixed by `/images`, and any span has the\nlabel `/http/method` with a value of 200.\n\nTroubleshooting\n---------------\n\nThis section contains troubleshooting content.\n\n### Slow performance\n\nIf your trace filter is complicated, it takes longer to run and could time\nout. To improve performance, simplify the filter.\n\n### No results\n\nIf your filter does not return any traces, check the following:\n\n- Be sure there are no spaces in the filter except the ones that\n separate the comparisons.\n\n- Be sure the letter case and spelling of all the words in the filter is\n correct. For example, if you misspell a keyword such as `method:GET`, the\n filter is interpreted as `label:method:GET`, which does not match any\n traces.\n\n- To test the filter terms one at a time, go to the\n [`list`](/trace/docs/reference/v1/rest/v1/projects.traces/list) API method and then use the\n APIs Explorer. If one of the terms returns no results, then that term\n might be the reason why no data is being returned.\n\n The APIs Explorer is open when the page displays a pane titled,\n **Try this method** . If necessary, click **Try it**, which opens the\n APIs Explorer."]]
