記錄查詢語言

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

如要深入瞭解 Logging 查詢語言設計，請參閱 Google API 篩選正式規格。

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

總覽

您可以在Google Cloud 控制台的記錄探索器、Logging API 或指令列介面中使用 Logging 查詢語言。 您可以使用 Logging 查詢語言查詢資料，以及編寫篩選器來建立接收器和記錄指標。

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

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

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

• 連詞限制：resource.type = "k8s_cluster" AND severity = "ERROR"

  注意： 如果查詢包含多個陳述式，您可以指定這些陳述式的聯結方式，也可以依賴 Cloud Logging 在陳述式之間隱含新增連詞限制 AND。舉例來說，假設查詢或篩選對話方塊包含兩個陳述式：resource.type = "gce_instance" 和 severity >= "ERROR"。實際查詢為 resource.type = "gce_instance" AND severity >= "ERROR"。 Cloud Logging 支援不相交限制 (OR) 和相交限制 (AND)。使用 OR 陳述式時，建議您使用括號將子句分組。

• 不相交限制：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」這兩個字詞，順序不拘。

注意： 如果查詢是使用多行比較編寫而成 (如上例所示)，比較結果會使用布林值 AND 運算子合併。

欄位路徑 ID

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

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

• httpRequest：{ cacheFillBytes、cacheHit、cacheLookup、cacheValidatedWithOriginServer、latency、protocol、referer、remoteIp、requestMethod、requestSize、requestUrl、responseSize、serverIp、status、userAgent }
• insertId
• jsonPayload { variable }
• labels { variable }
• 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 欄位是字串，您不可在其後加上任何子欄位名稱。

查詢 map 或 struct 欄位時，必須在運算式中保留鍵的大小寫和格式。

舉例來說，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。如需純量型別清單，請參閱純量通訊協定緩衝區型別清單。下表說明可轉換為記錄檔欄位類型的值：

欄位類型	允許的查詢值
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 文字的任何字串。內嵌引號必須使用反斜線逸出。 字串值必須以雙引號括住，才能逸出下列特殊字元： 開頭為 + (加號)、- (減號) 或 . (句號) 的字串。 含有 ~ (波浪符號)、 = (等號)、 () (括號)、 : (半形冒號)、 > (大於)、 < (小於)、 , (半形逗號)、 . (半形句號) 或 * (星號) 的字串。 任何逸出序列，例如 \t。
Timestamp	以 RFC 3339 或 ISO 8601 格式顯示的字串。示例：「2024-08-02T15:01:23.045Z」(RFC 3339)、「2024-08-02」(ISO 8601)。在查詢運算式中，RFC 3339 格式的時間戳記可使用「Z」或 ±hh:mm 指定時區。時間戳記的表示可精確到奈秒。
uintNN	未超出類型大小的任何不帶正負號整數。 例如：「1234」。

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

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

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"

注意： 註解會計入篩選條件的字元數上限 (20,000 個字元)。

比較運算子

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

• 所有數字類型：就數字而言，相等與不等的意義與一般無異。
• 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

在包含多個 Google Cloud 專案、資料夾或機構記錄項目的記錄值區中建立自訂記錄檢視時，log_id 函式非常實用。

log_id 函式的單一引數是不含網址編碼的記錄 ID：

log_id(non-URL-encoded log ID)

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

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

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

注意： 請勿對 log_id 函式的引數進行網址編碼。如果查詢陳述式使用引數的網址編碼 (例如 log_id("cloudaudit.googleapis.com%2Factivity"))，則不會比對到任何記錄項目。

投放

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

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

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

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

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

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

舉例來說，下列查詢會將 timestamp 欄位轉換為 STRING，並指定 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)

資源	查詢範例
機構	source(organizations/ORGANIZATION_ID)
資料夾	source(folders/FOLDER_ID)
Google Cloud 專案	source(projects/PROJECT_ID)

注意： 如果記錄值區包含來自多個 Google Cloud 專案、資料夾或機構的記錄項目，您可以使用 source 函式在該值區中建立自訂記錄檢視。

範例

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 函式。 舉例來說，如果您在搜尋列中輸入 world，則「記錄」會執行 SEARCH("world") 查詢。

您可以使用內建的 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"

注意： 記錄檔會將使用 YYYY-MM-DD 格式的查詢運算式解讀為 YYYY-MM-DDT00:00:00Z。

使用規則運算式

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

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

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

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

• 不會執行字串正規化；舉例來說，kubernetes 不會視為與 KUBERNETES 相同。詳情請參閱「比較運算子」一節。

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

• 您可以在規則運算式比較運算子 (=~ 和 !~) 右側的多個規則運算式之間使用布林運算子。

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

比對模式：

jsonPayload.message =~ "regular expression pattern"

不符合模式：

jsonPayload.message !~ "regular expression pattern"

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

注意：規則運算式查詢的潛在速度比一般文字查詢快。舉例來說，使用規則運算式查詢 jsonPayload.message =~ "foo.*bar|bar.*foo" 搜尋同時包含 foo 和 bar 的記錄項目，會比使用子字串查詢 jsonPayload.message : ("foo" AND "bar") 更快。

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

查詢類型	範例
標準查詢	sourceLocation.file =~ "foo"
使用不區分大小寫的搜尋查詢	labels.subnetwork_name =~ "(?i)foo"
含有引號的查詢	jsonPayload.message =~ "field1=\"bar.*\""
使用布林值 or 查詢	labels.pod_name =~ "(foo|bar)"
使用錨點查詢	logName =~ "/my%2Flog$"
查詢不符合模式	labels.pod_name !~ "foo"
使用布林運算子查詢	labels.env =~ ("^prod.*server" OR "^staging.*server")
以值開頭的查詢	logName =~ "^foo"
以值結尾的查詢	logName =~ "foo$"

注意： 如需 RE2 語法的詳細說明，請參閱 RE2 維基頁面。

快速尋找記錄項目

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

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

使用已建立索引的欄位

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

在下列查詢中使用這些時間戳記的值。如要建立 Logging 接受的時間戳記，請將日期和時間之間的空格換成字母 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"
  

  注意： 如果您使用搜尋列，且未將搜尋字詞加上雙引號，系統會使用 SEARCH 函式。SEARCH 函式會沿著權杖邊界執行搜尋。舉例來說，如果您在搜尋列中輸入 world，則記錄會執行 SEARCH("world") 查詢。先前的查詢符合 world，但不符合 worlds。

• 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.*"