進階記錄篩選器

本指南說明如何編寫進階記錄篩選器。只要利用這些運算式,您就可從任何數量的記錄中指定一組記錄項目。進階記錄篩選器可在記錄檢視器Stackdriver Logging API指令列介面中使用。

如要進一步瞭解基本篩選選項,請參閱基本記錄篩選器一文。

如果您想知道我們建議使用哪些篩選器尋找記錄,請參閱進階篩選器程式庫一文。

簡介

進階記錄篩選器是在專案中指定所有記錄項目子集的布林運算式。此運算式可用來執行以下任何操作:

  • 從特定記錄或記錄服務中選擇記錄項目。
  • 選擇某一時間範圍內的記錄項目。
  • 選擇滿足中繼資料或使用者定義欄位上之條件的記錄項目。
  • 選擇所有記錄項目的取樣百分比。

開始使用進階記錄篩選器

記錄檢視器中使用進階記錄篩選器:

  1. 前往 GCP 主控台的「Stackdriver Logging」>「Logs」(記錄) (「Logs Viewer」(記錄檢視器)) 頁面:

    前往「Logs Viewer」(記錄檢視器) 頁面

  2. 在頁面頂端選取現有 GCP 專案,或建立新專案。

  3. 使用下拉式選單,選取您要查看記錄的資源。

  4. 按一下搜尋篩選器方塊最右側的下拉式箭頭 (▾),然後選取 [Convert to advanced filter] (轉換為進階篩選器)

    轉換為進階記錄篩選器

您會看見如下圖所示的進階篩選器介面:

進階記錄篩選器 UI

進階篩選器介面沒有記錄選取選單,但提供 [Submit Filter] (提交篩選器) 按鈕。記錄檢視器會顯示符合篩選器所有指定條件的記錄項目。

以下是進階記錄篩選器的簡單範例:

    resource.type = "gce_instance" AND
    severity >= ERROR AND
    NOT textPayload:robot

此篩選器會比對 Compute Engine 中的記錄項目,這些項目的嚴重性值至少為 ERROR,而且其 textPayload 欄位中的任何位置都不包含 robot 字串。字串比較不區分大小寫。resourceseveritytextPayload 名稱是在 LogEntry 類型中定義的。

在您輸入時顯示建議,並以醒目方式強調字串:將進階篩選器輸入到記錄檢視器時,您可能會看見特定記錄項目欄位的建議。系統是根據篩選器語言和記錄檢視器載入的實際記錄項目組提供建議。如要選擇建議,請按 TAB。如果您沒有看見建議,請嘗試按 CTRL+ SPACE。篩選器運算式的不同部分會以不同顏色醒目顯示。如果您的運算式顯示亮紅色,即表示您到目前為止輸入的篩選器可能有錯誤或可能不完整。

未加引號的文字:如果字串不含空格或某些特殊字元,則不一定要用引號將字串括起來。這類省略引號的字串稱為「未加引號的文字」,如上一個範例中的 ERRORrobot 字詞。"v1.compute.instances.insert" 字串括在引號中,是因為字串中包含句號。如果您想要在字串內包含引號,請在引號前面加上反斜線 (``)。

最佳做法:請為您要與欄位值進行比較的字串加上引號。這可以防止比較的意義遭到改變 (這類錯誤往往難以察覺)。如果某個字母後面跟著一串英文字母、數字或底線 (_) 字元,則這類字詞可以省略引號。

使用鍵盤:如果您要使用鍵盤在搜尋篩選器方塊中輸入進階記錄篩選器,可以按下 ESC 結束編輯模式,然後按下 TAB 前往其他選項,例如「時間範圍選取器」下拉式選單、搜尋篩選器方塊最右側的下拉式箭頭 (▾),或是「Submit Filter」(提交篩選器) 按鈕。

進階記錄篩選器語法

本節討論如何建構進階記錄篩選器及如何執行比對。

語法標記法

進階記錄篩選器語法是以下列標記法構成:

  • a = e 意指 a 是運算式 e 的名稱。
  • a b 意指「a 後面跟著 b」。
  • a | b 意指「ab」。
  • ( e ) 用於分組。
  • [ e ] 意指 e 為選用。
  • { e } 意指 e 可重複零或多次。
  • "abc" 意指 abc 必須一字不漏地照原樣寫入。

語法摘要

本節提供進階記錄篩選器語法的概要總覽。我們已省略部分詳細資料,您可以在以下各節中閱讀這些詳細說明。

進階記錄篩選器是包含「運算式」的字串:

    expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }

comparison 可以是單一值或是布林運算式

  "The cat in the hat"
  resource.type = "gae_app"

第一行的範例是單一值的比較。這類比較屬於全域限制。系統會透過 has 運算子將該值與記錄項目中的每個欄位進行比較。在這個範例中,如果 LogEntry 中的任何欄位或是其酬載中包含「The cat in the hat」的詞句,即表示比較成功。

第二行的範例則是採用 [FIELD_NAME] [OP] [VALUE] 格式的布林運算式進行比較。比較元素的說明如下:

  • [FIELD_NAME]:是記錄項目中的一個欄位。例如:resource.type

  • [OP]:是比較運算子。例如:=

  • [VALUE]:為數字、字串、函式或「放入括號內」的運算式。例如 "gae_app"

以下幾節提供有關篩選器與比對的更多詳細資料。

布林運算子

布林運算子 ANDOR短路運算子NOT 運算子的優先順序最高,後面則依序是 ORAND。例如,以下兩個運算式的效果是相等的:

a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)

您可以忽略比較之間的 AND 運算子。您也可以使用 - (減號) 運算子取代 NOT 運算子。例如,以下兩個進階記錄篩選器是一樣的:

a=b AND c=d AND NOT e=F
a=b c=d -e=f

本說明文件一律使用 ANDNOT

比較

比較的格式如下:

[FIELD_NAME] [OP] [VALUE]

比較元素的說明如下:

  • [FIELD_NAME]:是記錄項目中欄位的路徑名稱。以下是幾個欄位名稱範例:

    resource.type
    resource.labels.zone
    resource.labels.project_id
    insertId
    jsonPayload.httpRequest.protocol
    labels."compute.googleapis.com/resource_id"
    

    詳情請參閱欄位路徑 ID 一節。

  • [OP]:是比較運算子,可以是下列其中一種運算子:

    =           # equal
    !=          # not equal
    > < >= <=   # numeric ordering
    :           # "has" matches any substring in the log entry field
    
  • [VALUE]:為數字、字串、函式或「放入括號內」的運算式。字串可用來表示任意文字,加上布林值、列舉與位元組字串值。進行比較之前,[VALUE] 會轉換為欄位類型。

如果 [VALUE] 是放入括號內的布林比較組合,欄位名稱與比較運算子會套用至每個元素。例如:

    jsonPayload.cat = ("siamese" OR "shorthair")
    jsonPayload.animal : ("nice" AND "pet")

第一個比較會檢查 cat 欄位是否包含「siamese」或「shorthair」的值。第二個比較會檢查 animal 欄位的值是否包含「nice」和「pet」這兩個字詞,順序不拘。

欄位路徑 ID

所有記錄項目都是 LogEntry 類型的執行個體。比較左側 (或開頭) 的 ID 必須是在 LogEntry 類型中定義的欄位。如要進一步瞭解可能的 ID 與其值,請參閱 LogEntry 類型

以下是記錄項目欄位的目前清單。如果適用,每個欄位後面都會跟著該欄位的下一層名稱:

  • httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status, userAgent }
  • insertId
  • jsonPayload { 變數 }
  • labels { 變數 }
  • logName
  • metadata { systemLabels, userLabels }
  • operation{ id, producer, first, last }
  • protoPayload { @type, 變數 }
  • receiveTimestamp
  • resource { type, labels }
  • severity
  • sourceLocation: { file, line, function }
  • spanId
  • textPayload
  • timestamp
  • trace

以下是您可在比較中使用的欄位路徑 ID 範例:

  • resource.type:如果您的第一個路徑 ID 是 resource,下一個 ID 必須是 MonitoredResource 類型的欄位。

  • httpRequest.latency:如果您的第一個路徑 ID 是 httpRequest,下一個 ID 必須是 HttpRequest 類型的欄位。

  • labels.[KEY] 如果您的第一個路徑 ID 是 labels,下一個 ID [KEY] 必須是出現在 labels 欄位中之鍵/值組合的其中一個鍵。

  • logName:由於 logName 欄位是字串,您不可在其後加上任何子欄位名稱。

如要進一步瞭解如何使用參考物件或陣列的欄位路徑 ID,請參閱物件與陣列類型一文。

受控資源類型

如要進行較快的搜尋,請指定受控資源類型。如需資源類型清單,請參閱受控資源類型一文。

例如,Compute Engine VM 使用資源類型 gce_instance,Amazon EC2 執行個體使用 aws_ec2_instance。以下範例顯示如何將搜尋限制於這兩種類型的 VM:

    resource.type = ("gce_instance" OR "aws_ec2_instance")

記錄中的受控資源類型值已編入索引,針對這些值使用子字串比對會導致查詢變慢。

遺漏欄位

如果您在篩選器中使用欄位名稱,且這個欄位未出現在記錄項目中,即表示欄位可能遺漏未定義已設為預設

  • 如果欄位是記錄項目酬載 (jsonPayloadprotoPayload) 的一部分,或者如果欄位位於記錄項目 labels 區段的標籤內,即表示遺漏欄位。使用遺漏欄位雖不會顯示錯誤,但使用遺漏欄位的所有比較會因此失敗,且不顯示任何訊息。

    例如:jsonPayload.nearest_storeprotoPayload.name.nickname

  • 如果欄位是在 LogEntry 類型中定義,即表示欄位已設為預設。在進行比較時,系統會當做欄位已顯示,且已有預設值。

    例如:httpRequest.remoteIptraceoperation.producer

  • 否則,欄位就是未定義,在使用篩選器之前會偵測出錯誤。

    例如:thudoperation.thudtextPayload.thud

如要在未測試欄位中特定值的情況下測試遺漏或設為預設的欄位是否存在,請使用 :* 比較。例如,如果 operation.id 欄位明確存在於記錄項目中,以下比較就會成功:

operation.id:*

物件與陣列類型

每個記錄項目欄位都可以保存「純量」、「物件」或「陣列」

  • 純量欄位可儲存單一值,像是 174.4-1string 也算是純量。可以與字串互相轉換的欄位,例如 DurationTimestamp 也是純量類型。

  • 物件類型可儲存一系列的具名值,類似以下內容的 JSON 值:

    {"age": 24, "height": 67}
    

    您可以參照物件內的值。舉例來說,如果 jsonPayload.x 包含先前的值,則 jsonPayload.x.age 會包含值 24

  • 陣列欄位可儲存值清單 (全都是相同類型)。舉例來說,一個保存測量數據的欄位可能會包含數字陣列:

    {8.5, 9, 6}
    

    進行比較時,如果 [FIELD_NAME] 屬於陣列欄位,每個陣列成員會與 [VALUE] 進行比較,並使用 OR 運算子將結果聯結在一起。舉例來說,如果 jsonPayload.shoeSize 是儲存 {8.5, 9, 6} 的陣列欄位,進行比較:

    jsonPayload.shoeSize < 7
    

    等於:

    8.5 < 7 OR 9 < 7 OR 6 < 7
    

    在這個範例中,整體比較有成功的結果。

值與轉換

評估比較的第一個步驟是將右側值轉換為記錄項目欄位類型。比較中允許使用純量欄位類型以及其他兩種類型,這些類型的值會表示為字串: DurationTimestamp。如需純量類型清單,請參閱純量通訊協定緩衝區類型清單。下表說明哪些值可以轉換為記錄欄位類型:

欄位類型 允許的篩選器 值
bool 大寫或小寫的「True」或「false」。例如:「True」、「true」。
bytes 包含任何位元組順序的字串。例如:「\377\377」。
Duration 包含帶正負號的小數,後跟「ns」、「us」、「ms」、「s」、「m」或「h」單位之一的字串。持續時間精確至奈秒。例如:「3.2s」。
enum 列舉類型常值的名稱,區分大小寫。例如:「WARNING」,這是 LogSeverity 類型的值。
double 任何數字,帶或不帶正負號及指數部分,或特殊值字串「NaN」、「-Infinity」與「Infinity」(無論是否以大寫表示)。例如:「-3.2e-8」、「nan」。
intNN 未超出類型大小的任何帶正負號整數。例如:「-3」。
string 包含 UTF-8 編碼或 7 位元 ASCII 文字的任何字串。內嵌引號必須使用反斜線逸出。
Timestamp RFC 3339 格式的字串。例如:「2014-10-02T15:01:23.045Z」。在篩選器運算式中,時間戳記可以使用「Z」或 ±hh:mm 指定時區。時間戳記的表示可精確到奈秒。
uintNN 未超出類型大小的任何不帶正負號整數。例如:「1234」。

如果嘗試轉換失敗,比較也會失敗。

當轉換需要字串時,如果數字或未加引號的文字不包含例如空格與運算子等特殊字元,也可以使用這些數字或未加引號的文字。同樣的,當轉換需要數字時,您可以使用內容為數字的字串。

intNNuintNN 類型代表各種大小的整數類型,例如 int32uint64。當寫入的值要轉換為 64 位元整數類型時,您應將值寫入為字串,例如「9223372036854775807」。

記錄欄位的類型

以下是判定記錄項目欄位類型的方式:

  • LogEntry 類型及元件類型定義的記錄欄位,都是通訊協定緩衝區欄位。通訊協定緩衝區欄位具有明確類型。

  • 屬於 protoPayload 物件一部分的記錄欄位也是通訊協定緩衝區欄位,並且具有明確類型。通訊協定緩衝區類型的名稱儲存在 protoPayload"@type" 欄位中。詳情請參閱 JSON 對應一文。

  • jsonPayload 內的記錄欄位具有接收記錄項目時從欄位值推測得出的類型:

    • 值為未加引號數字的欄位具有 double 類型。
    • 值為 truefalse 的欄位具有類型 bool
    • 值為字串的欄位具有類型 string

    長 (64 位元) 整數儲存在字串欄位中,因其無法確切表示為 double 值。

  • DurationTimestamp 類型只能在通訊協定緩衝區欄位中辨識。在別處,這些值會儲存在字串欄位中。

比較運算子

相等 (=!=) 與不等 (<<=>>=) 運算子的意義取決於左側欄位名稱的基本類型。

  • 所有數字類型:就數字而言,相等與不等的意義與一般無異。
  • bool:相等是指相同的布林值。不等由 true>false 定義。
  • enum:相等是指相同的列舉值。不等使用列舉常值的基本數值。
  • Duration:相等是指相同持續時間長度。不等是以持續時間長度為基礎。例如:就持續時間而言,"1s">"999ms"
  • Timestamp:相等是指時間中的相同時刻。如果 abTimestamp 值,a < b 表示 a 的時間早於 b
  • bytes:運算元會逐一按位元組,從左到右比較。
  • string:比較會略過字母大小寫。具體來說,兩個運算元都會先透過 NFKC_CF Unicode 正規化方式進行正規化,然後採用字典編纂順序進行比較。

子字串運算子 (:) 適用於 stringbytes,作用就像相等一樣,只不過右側運算元只需要等於左側欄位的某一部分。已建立索引之欄位上的子字串相符內容無法利用到記錄索引的好處。

全域限制

如果比較是由單一值組成,這類比較稱為「全域限制」。記錄會使用 has (:) 運算子判斷記錄項目中的任何欄位或是其酬載是否包含全域限制。如果包含全域限制,即表示比較成功。

依照全域限制編寫的最簡單進階記錄篩選器為單一值:

"The Cat in The Hat"

您可以使用 ANDOR 運算子結合全域限制,編寫比較特別的篩選器。舉例來說,如果您想顯示具有含 cat 的欄位及含 hatbat 的欄位的所有記錄項目,請將篩選器寫成:

(cat AND (hat OR bat))

這個範例有三個全域限制:cathatbat。這些全域限制會分別套用,之後再將結果合併在一起,如同不使用圓括號編寫運算式的情況一樣。

全域限制是在記錄中搜尋特定值的一種簡單方法。例如,如果您正在活動記錄中尋找包含任何提及 GCE_OPERATION_DONE 的項目,可以使用下列篩選器:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log" AND
    "GCE_OPERATION_DONE"

雖然全域限制相當簡單,但處理速度會比較緩慢。請參閱快速尋找記錄項目一節。

函式

您可在進階篩選器中使用內建函式做為全域限制:

function = identifier ( [ argument { , argument } ] )

其中 argument 可以是值、欄位名稱或是「放入括號內」的運算式。函式會在以下幾節中說明。

樣本

sample 函式會從所有記錄項目中選出一部分的記錄項目:

sample([FIELD], [FRACTION])

[FIELD] 是記錄項目中的欄位名稱,例如 logNamejsonPayload.a_field。欄位的值將決定記錄項目是否會列於樣本中。欄位類型必須為字串或數字值。將 [FIELD] 設定為 insertId 是個不錯的選擇,因為對這個欄位而言,每個記錄項目都有不同的值。

[FRACTION] 是包含具有 [FIELD] 值之記錄項目的一部分。這個數字要大於 0.0 且又不大於 1.0。舉例來說,如果您指定 0.01,則樣本會包含具有 [FIELD] 值的所有記錄項目約 1%。如果 [FRACTION] 為 1,則會選取具有 [FIELD] 值的所有記錄項目。

範例:以下篩選器會從 syslog 記錄中傳回 25% 的記錄項目:

    logName = "projects/my-project/logs/syslog" AND sample(insertId, 0.25)

詳細資料:一種以雜湊為基礎的確定性演算法,用以確認記錄項目是否已納入或是已從樣本中排除。結果樣本的正確性取決於雜湊值的分佈情形。如果雜湊值未平均分佈,結果樣本可能會偏移。最糟的狀況是,當 [FIELD] 一律包含相同的值,則結果樣本會包含所有記錄項目的 [FRACTION] 或是沒有任何記錄項目。

如果 [FIELD] 未出現在記錄項目中,即表示:

  • 已計算出雜湊值。
  • 以數字表示的雜湊值除以最大可能的雜湊值。
  • 如果結果小數小於或等於 [FRACTION],記錄項目會包含在樣本中;不然的話,就會從樣本中排除。

如果 [FIELD] 未出現在記錄項目中,即表示:

  • 如果 [FIELD] 是記錄項目酬載或 labels 區段的一部分,即使 [FRACTION] 是 1,該記錄項目也不會選入樣本中。
  • 否則系統會將記錄項目當做 [FIELD] 是位在記錄項目內,而 [FIELD] 的值則是預設值。預設值是由 LogEntry 類型決定。如要進一步瞭解遺漏及設為預設的欄位,請參閱遺漏欄位一節。

如要從樣本中排除已設定預設欄位的記錄項目,請使用欄位存在運算子 :*。下列篩選器會產生 1% 的記錄項目樣本,且這些記錄項目會明確提供 field 的值:

field:* AND sample(field, 0.01)

ip_in_net

ip_in_net 函式會判定記錄項目中的 IP 位址是否包含在子網路中。您可以使用此方法來確定要求來自內部還是外部來源。例如:

ip_in_net([FIELD], [SUBNET])

[FIELD] 是記錄項目中的字串值欄位,包含 IP 位址或範圍。欄位可以重複,如此就只有一個重複的欄位必須有包含在子網路中的位址或範圍。

[SUBNET] 是 IP 位址或範圍的字串常數。如本節稍後所述,如果 [SUBNET] 不是有效的 IP 位址或範圍,則視為錯誤。

範例:以下篩選器會測試 my_log 記錄中記錄項目的酬載 IP 位址:

    logName = "projects/my_project/logs/my_log" AND
    ip_in_net(jsonPayload.realClientIP, "10.1.2.0/24")

詳細資料:如果記錄項目的 [FIELD] 遺漏了、設為預設或不包含有效 IP 位址或範圍,函式會傳回 false。如要進一步瞭解遺漏及設為預設的欄位,請參閱遺漏欄位一文。

以下列出支援的 IP 位址與範圍的範例:

  • IPv4:10.1.2.3
  • IPv4 子網路:10.1.2.0/24
  • CIDR IPv6:1234:5678:90ab:cdef:1234:5678:90ab:cdef
  • CIDR IPv6 子網路:1:2::/48

按時間搜尋

您可在進階記錄篩選器介面中對要顯示記錄項目的日期與時間設定特定限制。例如,如果您要將下列條件新增至篩選器,記錄檢視器會顯示剛好在指示的 30 分鐘持續時間內的記錄項目,您將無法捲動到該日期範圍之外:

timestamp >= "2016-11-29T23:00:00Z"
timestamp <= "2016-11-29T23:30:00Z"

編寫時間戳記篩選器時,您必須使用如上所示的日期與時間格式。您也必須在搜尋篩選器方塊下方的時間範圍選取器中選取 [No limit] (無限制)

快速尋找記錄項目

篩選或查詢記錄項目時:

  • 使用已編入索引的欄位來搜尋。
  • 將必須搜尋的記錄項目數減到最少。

使用已建立索引的欄位

請為已建立索引的欄位指定確切的值。請勿使用子字串比對。以下記錄項目欄位已經建立索引:

臨時欄位索引

在 Stackdriver Logging 收到記錄項目之後,系統會將額外三個記錄項目欄位的一部分編入索引,持續一段時間。如果您嘗試快速回應系統的問題,搜尋這些欄位可能很有幫助。Stackdriver Logging 可能會變更未來為這三個欄位建立索引的方式,而不會發出通知:

  • severity:系統會為從「通知」(100) 到「緊急」(900) 的嚴重性值建立索引。如要利用索引,請只在建立索引的範圍中搜尋值。

  • httpRequest.status:系統會為從 201 到 511 的狀態值建立索引。如要利用索引,請只在建立索引的範圍中搜尋值。

  • operation.id:系統會為這些欄位的所有值建立索引。如要利用索引,請使用相等運算子搜尋此欄位;不要使用子字串搜尋。

如果您在最近的記錄項目中定期搜尋這些欄位,您也應該考慮使用 timestamp 欄位限制搜尋時間範圍。

將記錄、記錄項目與時間減到最少

縮減記錄和記錄項目的數量或搜尋的時間範圍,可讓您的搜尋速度更快。若能同時縮減這三個項目,效果更佳。

範例:使用正確的記錄名稱

您指定的記錄應包含您感興趣的記錄項目。請檢查您的其中一個記錄項目,確保您知道實際的記錄名稱。例如,記錄檢視器會顯示在名為「activity_log」的 Compute Engine 區段中有一個記錄。仔細觀察一下活動記錄項目,您會發現記錄實際的名稱為「compute.googleapis.com/activity_log」。

以下比較是錯誤的。這樣比較並不會比對出任何結果,因為比較中使用了錯誤的記錄名稱:

    logName = "projects/my-project-id/logs/activity_log"   # WRONG!

以下比較是正確的。這個比較從活動記錄中選擇了記錄項目。您必須以網址編碼記錄名稱,如下所示:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"

範例:選擇正確的記錄項目

如果您知道您想要的記錄項目來自特定 VM 執行個體,請予以指定。請檢查您要搜尋的其中一個記錄項目,來確認正確的標籤名稱。在以下範例中,instance_id 是其中一個已編入索引的標籤:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"
    resource.type = "gce_instance" AND
    resource.labels.instance_id = "6731710280662790612"

您必須為資源類型指定值。否則,instance_id 的比較不會使用索引。

範例:選擇正確的時間範圍

您應指定要搜尋的時間範圍。有一個快速方法可以確定 RFC 3339 格式的實用時間戳記,就是使用 Gnu/Linux date 指令:

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

請在下方的篩選器中使用這些時間戳記的值。如要建立 Stackdriver Logging 可接受的時間戳記,請用字母 T 取代日期與時間之間的空格。

例如,如要在最近的三小時內搜尋:

    timestamp >= "2016-06-27T14:40:00-04:00"

另一個例子是,如要在之前三小時與五小時之間搜尋:

    timestamp >= "2016-06-27T12:40:00-04:00" AND
    timestamp <= "2016-06-27T14:40:00-04:00"

如需使用時間戳記的其他範例,請參閱臨時欄位索引一文。

將全域與子字串搜尋數減到最少

輸入記錄篩選器時,請不要為了省事而訴諸捷徑。

範例:請勿在已編入索引的欄位中使用子字串

您正從 Apache2 網路伺服器搜尋記錄項目。您知道 Apache 記錄名為 apache-accessapache-error。您應該怎麼做?

  • 請勿使用子字串比對來幫您節省打字的時間:

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • 搜尋已編入索引的欄位時,使用完全相符比對:

        logName = ("projects/my-project-id/logs/apache-access" OR
                   "projects/my-project-id/logs/apache-error")
    

執行子字串搜尋時,已編入索引的欄位會喪失快速的特性。

範例:請勿使用全域搜尋

您正在酬載中搜尋帶有「Hello, Kitty」的記錄項目:

  • 請勿使用全域搜尋。其中一個原因是,這裡全都是子字串搜尋:

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • 即使必須保持子字串搜尋,也請勿將搜尋限制於單一欄位:

        textPayload:"Hello, Kitty"
    
  • 如果可以,使用相等測試:

        textPayload = "Hello, Kitty"
    
  • 如果您的記錄項目具有結構化酬載,參考酬載中的個別欄位:

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • 使用已建立索引的欄位來限制搜尋:

        logName = "projects/my-project_id/logs/somelog" AND
        jsonPayload.my_favorite_cat = "Hello, Kitty"
    

搜尋範例

這裡顯示的記錄項目是在搜尋篩選器方塊中符合進階記錄篩選器的記錄項目。如果「Jump to date」(跳到日期) 選單中含有值,顯示畫面會捲動到該時間點。以下是一些篩選器範例:

resource.type=gae_app

如果您從資源記錄選單中選取 [GAE 應用程式 (所有模組 ID)],並從記錄名稱選單中選取 [所有記錄],找到的記錄項目會與基本篩選器介面所顯示的記錄項目一樣。如需資源類型清單,請參閱受控資源清單

當您輸入時,記錄檢視器會建議完成像 resource.type 這樣的欄位。

resource.type=gae_app AND logName:request_log

從包含 request_log 的記錄名稱中尋找 App Engine 應用程式的記錄項目。請注意以下幾點:

  • = 運算子是完全相等。除了大小寫以外,資源類型必須與 "gae_app" 完全相同。
  • : 運算子是指「具有」。logName 欄位必須包含 request_log,大寫或小寫都可以。實際記錄名稱會長很多。使用 : 可能會導致搜尋速度變慢。
  • 兩個比較會用 AND 聯結。您也可以使用 OR,但如果您沒有填寫運算子,則會假定使用 AND
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

尋找具有兩個資源類型其中之一的記錄項目:Compute Engine VM 執行個體或 AWS EC2 VM 執行個體。記錄項目的 severity 至少須是 ERROR。在基本篩選器介面的嚴重性選單中選取 [ERROR] (錯誤) 可達到一樣的效果。在基本篩選器介面中,您無法查看多個資源類型的記錄。

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

[PROJECT_ID] 專案中尋找所有管理員活動稽核記錄項目。 專案中的所有稽核記錄都使用相同記錄名稱,但具有不同的資源類型。記錄 ID cloudaudit.googleapis.com/activity 必須在記錄名稱中以網址編碼。在比較中使用相等比對可加快搜尋的速度。詳情請參閱擷取稽核記錄一文。

unicorn

在任何欄位中尋找包含大寫或小寫 unicorn 的記錄項目。不屬於欄位比較一部分的搜尋字詞是「所有欄位」查詢。

unicorn phoenix

尋找在某些欄位中含有 unicorn,而在另一些欄位中含有 phoenix 的記錄項目。

textPayload:(unicorn phoenix)

尋找 textPayload 欄位中包含任意順序之 unicornphoenix 的記錄項目,兩個字詞之間會自動使用 AND

textPayload:"unicorn phoenix"

尋找 textPayload 欄位中包含 "unicorn phoenix" 字串的記錄項目。這與在基本篩選器介面中一樣。

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

尋找 30 分鐘內的記錄項目。

疑難排解

鍵盤瀏覽

如果您要使用鍵盤在搜尋篩選器方塊中輸入進階篩選器,且須前往頁面上的其他選單,請按下 ESC 結束編輯模式,然後按下 TAB 前往其他選項。

語法問題

如果您有關於進階篩選器運算式的問題,請檢查以下項目:

  • 您的篩選器是否遵守有關比對圓括號與引號的語法規則。

  • 您的記錄項目欄位名稱是否正確拼寫。

  • 布林運算子是否使用大寫字母 (ANDORNOT)。

  • 做為全域限制或位於比較右側的布林運算式應加上圓括號以確保意思清楚。例如,以下兩個篩選器看起來相同,實際上是不同的:

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • 未加引號的文字不得包含任何特殊字元。如有疑問,請加上雙引號。例如,因為內嵌子字串運算子 (:) 的關係,以下的第一個比較是無效的。比較必須用引號編寫:

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • gcloud logging 要求將篩選器放在雙引號中。如要在使用 gcloud logging 指令時針對逸出的特殊字元使用雙引號,請改用單引號包住完整篩選器:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    
  • 記錄檢視器基本篩選器中的搜尋運算式與進階記錄篩選器中的搜尋運算式不同。詳情請參閱基本與進階篩選器的差異一節。

  • 編寫時間戳記篩選器時,您必須在搜尋篩選器方塊下方的時間範圍選取器中選取 [No Limit] (無限制)

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Stackdriver Logging
需要協助嗎?請前往我們的支援網頁