本頁面由 Cloud Translation API 翻譯而成。

Cloud Trace 篩選器

本文說明如何在使用 Cloud Trace API list 方法時設定篩選器。您可以使用篩選器指定一或多個必須滿足的條件，才能傳回追蹤記錄。

這個頁面不適用於「Trace Explorer」頁面。如要篩選該頁面顯示的資料，請使用預先定義的篩選器 (列於「Span filters」窗格中)，或使用「Filter」列。詳情請參閱「尋找及探索追蹤記錄」。

篩選器總覽

追蹤記錄篩選器由一系列稱為條件的比較組成。追蹤記錄必須符合篩選器中的所有選取條件。例如，下列篩選器會比對延遲時間為一秒以上且包含時距的追蹤記錄，時距名稱為 /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] 開頭。

本頁面接下來的部分會說明使用 Cloud Trace API 時的篩選器。

要求篩選器範例

以下說明篩選器條件：

root:[NAME_PREFIX]

追蹤記錄的根時距名稱必須以 [NAME_PREFIX] 開頭。舉例來說，下列篩選器會比對名稱為 "/_ah/background" 的追蹤記錄，但不會比對名稱為 "/_ahx/background" 的追蹤記錄：

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 Explorer 頁面中的「Filter」欄位，如果您新增了註解 +^，按下 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 時，就會比對追蹤記錄。

疑難排解

本節包含疑難排解內容。

效能低落

如果追蹤記錄篩選器複雜，執行時間就會拉長，且可能會超時。如要提升篩選效能，請簡化篩選器。

沒有任何結果

如果篩選器並未傳回任何追蹤記錄，請執行以下檢查：

確認篩選器中除了分隔比較的空格以外，沒有任何其他空格。
確認篩選器中所有單字的字母大小寫和拼法正確無誤。例如，如果您拼錯了 method:GET 之類的關鍵字，系統會將篩選器誤認為 label:method:GET，導致無法比對出任何追蹤記錄。
如要一次測試一個篩選器條件，請前往 list API 方法，然後使用 API Explorer。如果其中某個條件未傳回任何結果，那麼該條件可能就是沒有傳回資料的原因。

當頁面顯示標題為「Try this method」的窗格時，表示 APIs Explorer 已開啟。如有需要，請按一下「Try it」，開啟 API Explorer。