Cloud Trace 篩選器

本文說明使用 Cloud Trace API list 方法時，如何設定篩選器。篩選器可讓您指定一或多項條件，必須符合這些條件才會傳回追蹤記錄。

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

篩選器總覽

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

根時距搜尋範例

如要將搜尋條件設為僅限根時距，請在搜尋條件之前或選用的 (+) 之後，加入 (^)。在「追蹤記錄探索器」頁面的「篩選器」欄位中，如果您加入註解 +^，按下 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 方法，然後使用 APIs Explorer。如果其中某個條件未傳回任何結果，可能就是沒有傳回資料的原因。

    如果頁面顯示名為「Try this method」(試試這個方法) 的窗格，表示 APIs Explorer 已開啟。如有需要，請按一下「試試看」，開啟 APIs Explorer。