Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Cloud Trace 篩選器

Cloud Trace 篩選器可讓您查詢 Trace API list 方法，只擷取符合特定條件的追蹤記錄，例如範圍名稱、最短延遲時間、HTTP 屬性或標籤。

這些篩選器運算式不適用於 Google Cloud 控制台的「Trace Explorer」頁面。在「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]。

本頁面其餘部分將說明 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 方法，然後使用 API Explorer。如果其中一個字詞沒有傳回任何結果，則該字詞可能是沒有傳回資料的原因。

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