記錄查詢語言

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

本文將概略說明您用來查詢及篩選 Cloud Logging 資料的記錄查詢語言。

如要進一步瞭解 Logging 查詢語言設計，請參閱 Google API 篩選功能的正式規格。

如需常見查詢的範例，請參閱「使用記錄檔探索工具的查詢範例」。

總覽

您可以在Google Cloud 主控台的 Logs Explorer 中使用 Logging 查詢語言、Logging API 或指令列介面。您可以使用 Logging 查詢語言查詢資料，並編寫篩選器來建立接收器和以記錄為基礎的指標。

查詢是布林運算式，用於指定所選 Google Cloud 資源 (例如 Google Cloud 專案或資料夾) 中的所有記錄項目子集。

您可以使用邏輯運算子 AND 和 OR，根據 LogEntry 索引欄位建立查詢。在以下範例中使用 resource.type 欄位，記錄查詢語言文法如下所示：

• 簡單限制：resource.type = "k8s_cluster"

• 並列限制：resource.type = "k8s_cluster" AND severity = "ERROR"

• 選項限制：resource.type = "k8s_cluster" OR resource.type = "gce_instance"

  • 替代做法：resource.type = ("k8s_cluster" OR "gce_instance")

• 複雜的並列/選項運算式：resource.type = "k8s_cluster" AND (severity = "ERROR" OR "error")

以下是查詢範例：

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

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

語法標記法

以下各節將概略說明記錄查詢語言的語法，並詳細討論查詢的結構和比對方式。部分範例會使用註解提供說明文字。

注意事項：

• 查詢的長度不得超過 20,000 個半形字元。

• Logging 查詢語言不區分大小寫，但規則運算式和邏輯運算子 (例如 AND 和 OR) 除外。邏輯運算子必須大寫。

語法摘要

您可以將 Logging 查詢語言語法視為查詢和比較。

查詢是包含「運算式」的字串：

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

比較可以是單一值或布林運算式：

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

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

第二行的範例則是採用 [FIELD_NAME] [OP] [VALUE] 格式的布林運算式進行比較。比較項目包含三個元件：

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

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

• [VALUE] 是���字、字串、函式或「放入括號內」的運算式。例如，"k8s_cluster"。如果是 JSON 空值，請使用 NULL_VALUE。

布林運算子

布林運���子 AND 和 OR 是短路運算子。NOT 運算子的優先順序最高，其次為 OR 和 AND。例如，以下兩個運算式的效果是相等的：

"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"

本說明文件一律使用 AND 和 NOT。

除了記錄檢視畫面使用的篩選器，您可以使用 AND、OR 和 NOT 運算子篩選所有篩選器。記錄檢視畫面僅支援 AND 和 NOT 作業。

如要在同一個運算式中結合 AND 和 OR 規則，您必須使用括號巢狀化規則。如果您未使用括弧，查詢可能無法正常運作。

布林運算子一律使用大寫。系統會將小寫的 and、or 和 not 剖析為搜尋字詞。

比較

比較的格式如下：

[FIELD_NAME] [OP] [VALUE]

比較項目包含三個元件：

• [FIELD_NAME]：是記錄項目中欄位的欄位路徑 ID。以下是這些 ID 的範例：

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

  如果欄位路徑 ID 的組成元素含有特殊字元，則該組成元素必須使用雙引號括住。舉例來說，compute.googleapis.com/resource_id 必須使用雙引號，因為它包含正斜線 /。

  詳情請參閱本文件的「欄位路徑 ID」一節。

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

  =           -- equal
  !=          -- not equal
  > < >= <=   -- numeric ordering
  :           -- "has" matches any substring in the log entry field
  =~          -- regular expression search for a pattern
  !~          -- regular expression search not for a pattern
  

如要瞭解如何使用規則運算式搜尋記錄項目，請參閱「使用規則運算式」。

• [VALUE]：為數字、字串、函式或「放入括號內」的運算式。字串可用來表示任意文字，加上布林值、列舉與位元組字串值。進行比較之前，[VALUE] 會轉換為欄位類型。如果是 JSON 空值，請使用 NULL_VALUE。

如要篩選 JSON 空值，請使用下列語法：

jsonPayload.field = NULL_VALUE      -- includes "field" with null value
NOT jsonPayload.field = NULL_VALUE  -- excludes "field" with null value

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

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

第一個比較會檢查 cat 欄位是否包含「longhair」或「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, variable }
• 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 欄位是字串，您不可在其後加上任何子欄位名稱。

查詢地圖或結構體欄位時，請務必在運算式中保留鍵的大小寫和格式。

舉例來說，jsonPayload 是結構體欄位，因此巢狀在 jsonPayload 內的欄位名稱 (例如 jsonPayload.end_time) 與 jsonPayload.endTime 不同。同樣地，對於 labels 這類地圖欄位，標籤鍵 labels.env_name 與 labels.envName 不同。相反地，在查詢一般通訊協定緩衝區欄位 protoPayload 時，您不需要保留大小寫。

如要瞭解 LogEntry 欄位類型，請參閱 google.logging.v2 參考資料。

特殊字元

如果 LogEntry 欄位含有特殊字元，則記錄欄位必須加上引號。例如：

jsonPayload.":name":apple

jsonPayload."foo.bar":apple

jsonPayload."\"foo\"":apple

如需特殊字元的清單，請參閱「值和轉換」中的 string 部分。

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

受控資源類型

如要加快查詢速度，請指定受控資源類型。如需資源類型清單，請參閱「受控資源類型」一文。

舉例來說，Compute Engine VM 使用資源類型 gce_instance，Amazon EC2 執行個體則使用 aws_ec2_instance。以下範例說明如何將查詢限制為兩種 VM 類型：

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

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

遺漏欄位

如果您在查詢中使用欄位名稱，且該欄位未出現在記錄項目中，即表示欄位可能遺漏、未定義或已設為預設：

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

  例如：jsonPayload.nearest_store、protoPayload.name.nickname

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

  例如：httpRequest.remoteIp、trace、operation.producer

• 否則，欄位就是未定義，在使用查詢之前會偵測出錯誤。

  例如：thud、operation.thud、textPayload.thud

如要在未測試欄位中特定值的情況下測試遺漏或設為預設的欄位是否存在，請使用 :* 比較。舉例來說，如果記錄項目中明確包含欄位 operation.id，則下列比較作業會成功：

operation.id:*

請注意下列查詢的行為：

• 在缺少欄位上使用布林 NOT 運算子時，結果會是 TRUE：

  -- Returns TRUE
  NOT missingField=foo
  

• 在遺漏欄位上使用不相等比較運算子 != 時，結果為 FALSE：

  -- Returns FALSE
  missingField!=foo
  

物件與陣列類型

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

• 純量欄位可儲存單一值，像是 174.4 或 -1。string 也��是純量。可以與字串互相轉換的欄位，例如 Duration 和 Timestamp 也是純量類型。

• 物件類型可儲存一系列的具名值，類似以下內容的 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
  

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

值與轉換

評估比較的首要步驟，是將右側值轉換為記錄項目欄位的類型。比較作業允許使用標量欄位類型，以及兩種值以字串表示的額外類型：Duration 和 Timestamp。如需純量類型的清單，請參閱純量通訊協定緩衝區類型清單。下表說明哪些值可轉換為記錄欄位類型：

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

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

類型 intNN 和 uintNN 代表各種大小的整數類型，例如 int32 和 uint64。當您要將值寫入並轉換為 64 位元整數型別時，請將值寫入為字串，例如「9223372036854775807」。

記錄欄位的類型

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

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

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

  當您篩選與 Any 訊息類型相關聯的欄位時，系統會自動遍歷 value 欄位。因此，請勿將其納入查詢。詳情請參閱「疑難排解」。

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

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

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

• Duration 和 Timestamp 類型只能在通訊協定緩衝區欄位中辨識。在其他地方，這些值會儲存在字串欄位中。

註解

註解以兩個破折號 (--) 開頭，系統會忽略破折號後面的任何文字，直到行結尾為止。註解可放在篩選器開頭、詞彙之間，以及篩選器結尾。

您可能會在下列情況下使用註解：

• 如要為複雜篩選條件加上註解，說明子句的功能：

   -- All of our target users are emitted by Compute Engine instances.
   resource.type = "gce_instance"
   -- Looking for logs from "alex".
   jsonPayload.targetUser = "alex"

• 如要透過新增或移除註解前置字串，快速啟用或停用子句，請按照下列步驟操作：

   resource.type = "gce_instance"
   -- jsonPayload.targetUser = "alex"
   jsonPayload.targetUser = "kiran"
   -- jsonPayload.targetUser = "sasha"

比較運算子

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

• 所有數字類型：就數字而言，相等與不等的意義與一般無異。
• bool：相等是指相同的布林值。不等由 true>false 定義。
• enum：相等是指相同的列舉值。不等使用列舉常值的基本數值。
• Duration：相等是指相同持續時間長度。不等是以持續時間長度為基礎。例如：就持續時間而言，"1s">"999ms"。
• Timestamp：相等是指時間中的相同時刻。如果 a 和 b 為 Timestamp 值，a < b 表示 a 的時間早於 b。
• bytes：運算元會逐一按位元組，從左到右比較。
• string：比較會略過字母大小寫。具體來說，兩個運算元都會先透過 NFKC_CF Unicode 正規化方式進行正規化，然後採用字典編纂順序進行比較。不過，規則運算式搜尋並未經過標準化處理。如要進一步瞭解如何使用規則運算式搜尋記錄項目，請參閱「使用規則運算式」。

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

全域限制

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

依照全域限制編寫的最簡單查詢為單一值：

"The Cat in The Hat"

您可以使用 AND 和 OR 運算子結合全域限制，編寫比較特別的查詢。舉例來說，如果您想顯示具有含 cat 的欄位及含 hat 或 bat 的欄位的所有記錄項目，請將查詢寫成：

("cat" AND ("hat" OR "bat"))

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

全域限制是一種在記錄中搜尋特定值的方法。例如，如果您正在活動記錄中尋找包含任何提及 GCE_OPERATION_DONE 的項目，可以使用下列查詢：

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

建議您使用內建 SEARCH 函式和查詢已編入索引的欄位，而不要使用可能速度較慢的全域限制。詳情請參閱本文件中的「快速尋找記錄項目」。

函式

您可以在查詢中使用內建函式做為全域限制：

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

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

log_id

log_id 函式可用於在記錄值區中建立自訂記錄檢視畫面，該值區包含許多 Google Cloud 專案、資料夾或機構的記錄項目。

log_id 函式的單一引數為非網址編碼的記錄 ID：

log_id(non-URL-encoded log ID)

舉例來說，下列查詢會傳回所有活動稽核記錄：

log_id("cloudaudit.googleapis.com/activity")

在上一個查詢中，引數只包含英數字元和特殊字元 (/、_、-、.)。

投放

cast 函式會接受兩個參數：要轉換的 LogEntry 欄位，以及欄位要轉換成的資料類型：

cast([FIELD], [TYPE][, OPTION])

上一個運算式的參數定義如下：

• [FIELD]：記錄項目中的欄位名稱，例如 logName 或 jsonPayload.a_field。

• [TYPE]：資料類型，例如 STRING、INT64、FLOAT64、BOOL。

  • TIMESTAMP 或 DURATION：部分資料類型提供其他選項，例如為 TIMESTAMP 資料類型指定 IANA 時區資料庫時區。

舉例來說，下列查詢會將 timestamp 欄位轉換為字串，並指定 America/New_York 時區：

cast(timestamp, STRING, TIME_ZONE("America/New_York")) =~ "^2025-04-02.*"

regexp_extract

使用 regexp_extract 函式找出與規則運算式相符的第一個子字串：

REGEXP_EXTRACT([FIELD], [REGULAR_EXPRESSION])

在上述運算式中，欄位的定義如下：

• [FIELD]：記錄項目中的欄位名稱，例如 logName 或 jsonPayload.a_field。
• [REGULAR_EXPRESSION]：必須包含一個擷取群組 ((...)) 的 RE2 規則運算式。如果規則運算式需要額外分組，則必須使用非擷取群組 (?:...)。多個擷取群組或沒有擷取群組都會導致錯誤。

您可以鏈結 cast 和 regexp_extract 函式：

CAST(REGEXP_EXTRACT(CAST(timestamp, STRING), "\\d+:\\d+:(\\d+)"), INT64) < 30

上一個範例將 timestamp 欄位轉換為字串。規則運算式會擷取 timestamp 字串的秒數欄位值，然後將其轉換為整數，以便執行數值比較。當時間戳記的秒數欄位小於 30 時，查詢結果會列出記錄項目。

來源

source 函式會比對機構、資料夾和 Google Cloud 專案階層中特定資源的記錄項目。

source 函式與子項資源不相符。舉例來說，使用 source(folders/folder_123) 會比對 folder_123 資源的記錄，而非 folder_123 內 Google Cloud 專案資源的記錄。

如要查詢特定資源層級的記錄，請使用下列語法：

source(RESOURCE_TYPE/RESOURCE_ID)

範例

sample 函式會選取記錄項目總數的一部分：

sample([FIELD], [FRACTION])

[FIELD] 是記錄項目中的欄位名稱，例如 logName 或 jsonPayload.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

SEARCH 個函式

您可以使用內建的 SEARCH 函式，在記錄資料中尋找字串：

SEARCH([query])
SEARCH([field], [query])

SEARCH 函式的兩種形式都包含 query 引數，必須以字串常值格式呈現。在第一種形式中，系統會搜尋整個記錄項目。在第二種表單中，您可以指定要搜尋的記錄項目欄位。

您必須指定 query 欄位。如未指定這個欄位，系統會傳回錯誤。

處理 SEARCH 函式時，文字分析器會處理 query 字串，將字串分割為符記。Cloud Logging 一律會執行不區分大小寫的比較作業，即使是使用反引號包裝的符記也是如此。這與 BigQuery 的行為不同，後者會保留以反引號包圍的符記大小寫。如要瞭解分析器規則，請參閱 BigQuery 說明文件的「文字分析器規則」一節。

建構搜尋時，請考量下列事項：

• 符記不區分大小寫。以下函式會產生相同的結果：

  SEARCH("world")
  SEARCH("World")
  

  當單一欄位包含符記「world」時，前述函式會比對記錄項目。由於 SEARCH 會執行完全比對，而非子字串比對，因此先前的函式不會比對值為「worldwide」的欄位。

• 如果您未指定要搜尋的欄位，當記錄項目包含所有符記時，SEARCH 函式就會比對該記錄項目。不過，符記的順序不重要，而且不一定要在記錄項目的相同欄位中找到符記。

  以下函式會產生相同的結果，且會比對含有「hello」和「world」符記的記錄項目：

  SEARCH("hello world")
  SEARCH("World hello")
  

• 如果您指定要搜尋的欄位，SEARCH 函式只會搜尋該欄位。如果該欄位包含所有符記，就會產生比對結果，但符記的順序不重要。

  只有在 textPayload 欄位包含「hello」和「world」符記時，下列函式才會產生比對結果：

  SEARCH(textPayload, "hello world")
  

• 如要對詞組進行大小寫不敏感的完全比對，請在該詞組前後加上反斜線。例如，下列函式會與「hello world」字串相符：

  SEARCH("`hello world`")
  SEARCH("`Hello World`")
  SEARCH("`HELLO WORLD`")
  

  由於下列函式使用反引號，因此會產生不同的結果：

  SEARCH("`hello world`")
  SEARCH("`world hello`")
  

Logging 查詢語言支援多種搜尋記錄資料的方式。搜尋字串時，使用 SEARCH 函式比執行全域搜尋或子字串搜尋更有效率。不過，您無法使用 SEARCH 函式比對非文字欄位。如需執行搜尋作業的指引，請參閱「減少全域和子字串搜尋」。

按時間搜尋

您可在介面中對要顯示記錄項目的日期與時間設定特定限制。舉例來說，如果您要將下列條件新增至查詢，結果窗格會顯示剛好在指示的 30 分鐘持續時間內的記錄項目，您將無法捲動到該日期範圍之外：

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

編寫含有時間戳記的查詢時，您必須使用先前所示的日期與時間格式。

您也可以使用 timestamp 快速鍵搜尋記錄項目。舉例來說，您可以輸入日期和比較運算子，取得特定日期後的所有記錄項目：

timestamp > "2023-11-29"

使用規則運算式

您可以使用規則運算式建構查詢，並為接收器、指標和使用記錄篩選器的任何位置建立篩選器。舉例來說，您可以在記錄檔探索工具和 Google Cloud CLI 中使用規則運算式。

規則運算式是定義搜尋內容的字元序列。記錄查詢語言使用 RE2 語法。如需 RE2 語法的完整說明，請參閱 GitHub 上的 RE2 維基百科。

規則運算式查詢具有下列特性：

• 只有字串類型的欄位才能與規則運算式相符。

• 系統不會執行字串正規化作業，舉例來說，kubernetes 不等於 KUBERNETES。詳情請參閱「比較運算子」一節。

• 查詢不區分大小寫，且預設不會錨定。

• 布林運算子可用於規則運算式比較運算子 =~ 和 !~ 右側的多個規則運算式之間。

規則運算式查詢的結構如下：

比對模式：

jsonPayload.message =~ "regular expression pattern"

不符合模式：

jsonPayload.message !~ "regular expression pattern"

=~ 和 !~ 會將查詢變更為規則運算式查詢，且您要比對的模式必須位於雙引號內。如要查詢包含雙引號的模式，請使用反斜線逸出。

使用規則運算式查詢記錄檔的範例

快速尋找記錄項目

如要有效尋找記錄項目，請按照下列步驟操作：

• 使用已建立索引的欄位查詢。
• 將必須搜尋的記錄項目數減到最少。

使用已建立索引的欄位

Logging 一律會為下列 LogEntry 欄位建立索引：

• resource.type
• resource.labels.*
• logName
• 嚴重性
• 時間戳記
• insertId
• operation.id
• trace
• httpRequest.status
• labels.*
• split.uid

您也可以將自訂索引欄位新增至任何記錄值區，或使用 SEARCH 函式來加快查詢速度。

最佳化查詢

縮減記錄和記錄項目的數量或搜尋的時間範圍，可讓您的搜尋速度更快。更棒的是，您可以減少這三項。

範例：使用 SEARCH 函式

您可以使用 SEARCH 函式，利用索引來改善查詢，而非執行全域或子字串搜尋。

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

您指定的記錄應包含您感興趣的記錄項目。請檢查您的其中一個記錄項目，確保您知道實際的記錄名稱。舉例來說，結果窗格顯示 Compute Engine 部分包含名為「activity」的記錄。仔細檢查「管理員活動」稽核記錄項目後，您會發現記錄的名稱其實是「cloudaudit.googleapis.com/activity」。

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

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

以下比較是正確的。從「管理員活動」稽核記錄項目中選擇記錄項目。您必須以網址編碼記錄名稱，如下所示：

logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

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

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

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

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

指定搜尋的時間範圍。如要快速判斷有用的 RFC 3339 格式時間戳記，可以使用 GNU/Linux date 指令：

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

請在下列查詢中使用這些時間戳記的值。如要建立記錄可接受的時間戳記，請將日期和時間之間的空格替換為字母 T。

例如，如要在最近的三小時內搜尋：

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

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

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

盡量減少選項限制

查詢如果只使用聯合限制 AND，就能更有效地使用索引。您可以使用析取限制 OR，但這類查詢可能會執行緩慢，��無法使用索引。

舉例來說，SEARCH("foo") AND SEARCH("bar") 會使用索引，因此比 SEARCH("foo") OR SEARCH("bar") 這類查詢更快。

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

輸入查詢時，請避免使用捷徑。

範例：請勿使用全域搜尋

如果您要搜尋酬載中含有「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"
     

• 請使用 SEARCH 函式，並指定要比對的完整文字。SEARCH 函式會執行不區分大小寫的比對：

    SEARCH("Hello Kitty")
    

  請勿使用 SEARCH 函式並指定部分文字。例如，下列函式不符合「Hello Kitty」。

    SEARCH("Hello Kit")
    

搜尋範例

這裡顯示的記錄項目是在查詢中符合的記錄項目。如果「Jump to time」(跳到時間) 選單中含有值，顯示畫面會捲動到該時間點。以下列舉幾個查詢範例：

resource.type=k8s_cluster

找出所有 Google Kubernetes Engine 記錄項目。如需資源類型清單，請參閱受控資源清單。

當您輸入時，查詢窗格會建議完成像 resource.type 這樣的欄位。

resource.type=k8s_cluster AND logName:request_log

從包含 request_log 的記錄名稱中尋找 Google Kubernetes Engine 叢集的記錄項目。請注意以下幾點：

• = 運算子是完全相等。除了大小寫以外，資源類型必須與 "k8s_cluster" 完全相同。
• : 運算子是指「具有」。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 欄位同時包含 unicorn 和 phoenix 的記錄項目 (順序不拘)，AND 會隱含在兩個字詞之間。

textPayload:"unicorn phoenix"

尋找 textPayload 欄位包含 "unicorn phoenix" 字串的記錄項目。

NOT textPayload: "unicorn phoenix"

尋找 textPayload 欄位「不含」"unicorn phoenix" 字串的記錄項目。這類查詢可減少不必要的記錄項目。

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

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

疑難排解

語法問題

如果您有關於查詢運算式的問題，請檢查以下項目：

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

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

• 布林運算子是否使用大寫字母 (AND、OR、NOT)。

• 請確認您使用 NULL_VALUE 來表示 JSON 空值。

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

  insertId = "ABC-1" OR "ABC-2"  -- ERROR!?
  insertId = ("ABC-1" OR "ABC-2")
  

• 未加引號的文字不得包含任何特殊字元。如有疑問，請加上雙引號。例如，因為內嵌子字串運算子 (:) 的關係，以下的第一個比較是無效的。比較必須用引號編寫：

  insertId = abc:def  -- ILLEGAL!
  insertId = "abc:def"
  

• Google Cloud CLI 要求將查詢放在雙引號中。如要在使用 gcloud logging 指令時針對逸出的特殊字元使用雙引號，請改用單引號包住完整查詢：

  gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
  gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
  

• 當您篩選與 Any 訊息類型相關聯的欄位時，系統會自������歷 value 欄位。因此，請勿在查詢中加入 value。

  舉例來說，AuditLog 訊息中的 Status 欄位有 details 欄位，其類型為 google.protobuf.Any。如要查詢 details 欄位，請在指定篩選器時略過 value 欄位：

  • 正確做法

    protoPayload.status.details.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"
    

  • 錯誤做法

    protoPayload.status.details.value.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"