使用 Logging 查詢語言建構及儲存查詢

本文說明如何使用記錄檔探索工具擷取及分析記錄，方法是在查詢編輯器欄位中撰寫查詢，以及從預先定義的篩選器選項中選取。您建立的查詢會以記錄查詢語言撰寫。

您也可以在「記錄檔總管」頁面中儲存查詢，或使用 Logging API 方法 savedQueries.create 儲存查詢。

事前準備

「記錄檢視者」角色 (roles/logging.viewer) 提供記錄檢視權限。 舉例來說，獲得這個角色後，您就能撰寫及執行查詢。您也可以將查詢儲存為私人查詢，並執行私人和共用查詢。不過，這個角色無法儲存或修改共用查詢。如要儲存或修改共用查詢，請確認您已獲授 Logging 管理員角色 (roles/logging.admin)，這項角色提供 Cloud Logging 的完整存取權。

執行下列其中一個步驟：

  • 如要取得寫入及執行查詢、執行及儲存私密查詢，以及執行共用查詢所需的權限，請要求管理員授予您專案的記錄檢視者 (roles/logging.viewer) IAM 角色。

  • 如要取得撰寫及執行查詢、執行及儲存私人查詢，以及執行、建立及管理共用查詢所需的權限，請要求管理員授予您專案的 Logging Admin (roles/logging.admin) IAM 角色。

如要進一步瞭解必要的 IAM 權限，請參閱控制台的權限 Google Cloud 。

建構查詢

如要使用 Google Cloud 控制台建構查詢，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Logs Explorer」頁面：

    前往「Logs Explorer」(記錄檔探索工具)

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

  2. 選取要查看記錄的 Google Cloud 專案或其他 Google Cloud資源。

  3. 使用「查詢」窗格建構查詢。

    「查詢」窗格提供多種方式來建構及執行查詢運算式：

    • 搜尋所有記錄檔欄位中的文字。
    • 從篩選選單中選取選項。
    • 使用查詢編輯器撰寫或修改查詢。
    • 在「查詢庫」中查看及執行已儲存、近期和建議的查詢。

搜尋記錄檔欄位中的文字

如要搜尋所有記錄檔欄位中的文字，並找出所有相符的記錄檔項目，請在「Query」(查詢) 窗格的搜尋欄位中輸入搜尋字詞。

您可以搜尋字詞和詞組，搜尋字詞可包含布林運算子和規則運算式：

  • 如要執行區分大小寫的搜尋，請使用規則運算式。

  • 如要執行不區分大小寫的搜尋，請在權杖界線輸入搜尋字詞，不要使用反引號或雙引號。

    舉例來說，如要搜尋包含「hello」和「world」的記錄項目，請輸入「hello world」。這個指令會轉換為 SEARCH("hello world")，並比對包含 hello 和 world 符記的記錄項目 (順序不限)。由於搜尋不區分大小寫，因此搜尋結果也會包含含有 Hello 和 World 符記的記錄項目。搜尋內容與權杖 worlds 不符。

  • 如要執行不區分大小寫的詞組搜尋 (以符記邊界為準)，請在詞組前後加上反引號。

    舉例來說，如要搜尋「hello world」，請輸入「`hello world`」。這個指令會轉換為 SEARCH("`hello world`")，比對含有符記 hello world 的記錄項目。搜尋內容與權杖 hello worlds 不符。

  • 如要執行不區分大小寫的子字串搜尋，請在文字前後加上雙引號。舉例來說，"hello world" 符合 Hello World 和 Hello world。由於系統不會沿著符記邊界執行搜尋，因此相同的查詢也會比對 hello worlds。

如要在查詢運算式中查看搜尋字詞，請啟用「顯示查詢」。

輸入搜尋字詞後，按一下「執行查詢」或按下 Enter 鍵。「Query results」(查詢結果) 窗格會顯示查詢結果。

布林運算子

系統會將搜尋欄位項目轉換為布林運算式，指定所選 Google Cloud 資源中所有記錄項目的子集。

搜尋欄位支援使用布林運算子 AND、OR 和 NOT。在搜尋運算式中使用布林運算子時，請注意下列事項：

  • 您無法使用括號巢狀規則。搜尋運算式中的任何括號都會剖析為搜尋字詞。
  • 布林運算子必須大寫。小寫的 and、or 和 not 會剖析為搜尋字詞，而非運算子。

如果未加入任何運算子，系統會以 AND 連結所有搜尋字詞和詞組。您可以忽略搜尋字詞之間的 AND 運算子。

AND 和 OR 運算子是短路運算子。您可以在同一個運算式中合併 AND 和 OR 規則。舉例來說，如果混合使用這兩個運算子，運算式 a AND b OR c AND d 會變成下列 Logging 查詢語言運算式：

"a"
"b" OR "c"
"d"

NOT 運算子的優先順序最高，其次是 OR 和 AND， 依此類推。

NOT 運算子會對後續字詞執行否定運算。舉例來說，NOT error 會傳回不含 error 的記錄項目。您也可以使用 - (減號) 運算子取代 NOT 運算子。舉例來說，以下兩個查詢相同：

"response" AND "successful" AND NOT "error"

"response successful" -"error"

如果 - (減號) 運算子位於引號外，這項邏輯也適用於片語。舉例來說，以下兩個查詢相同：

-"response successful"

NOT "response successful"

使用篩選器選單建構查詢

您可以使用「Query」(查詢) 窗格中的篩選器選單，將資源、記錄名稱、記錄嚴重程度和關聯性參數新增至「query-editor」(查詢編輯器) 欄位。這些選項對應於 Logging 中所有記錄的 LogEntry 欄位。

「資源」和「記錄名稱」選單中的選項，是從 Cloud Logging 儲存的記錄項目衍生而來。

  • 資源：可指定 resource.type 和相關聯的 resource.labels。您可以使用這個篩選器選單選取單一資源類型，以及要套用至查詢的零或多個資源標籤。資源參數會以邏輯運算子 AND 聯結。
  • 記錄檔名稱：可指定 logName。您可以選取多個記錄名稱，套用至查詢。選取多個記錄名稱時，系統會使用邏輯運算子 OR。
  • 嚴重性：可指定嚴重性。您可以同時選取多個嚴重性等級，並套用至查詢。選取多個嚴重程度時，系統會使用邏輯運算子 OR。
  • 依據關聯性排序：可讓您以「上/下層」格式分組及查看記錄項目。詳情請參閱「關聯記錄項目」。

如要使用任一篩選器選單，請按照下列步驟操作：

  1. 展開「Query」(查詢) 窗格中任一篩選器選單的「Menu」(選單) 。

  2. 調整篩選器參數。

  3. 按一下 [套用]。查詢編輯器欄位中會顯示參數。

    如要在查詢運算式中查看搜尋字詞，請啟用「顯示查詢」。

  4. 查看查詢之後，按一下「執行查詢」。「Query results」(查詢結果) 窗格會顯示查詢結果。

對於特定 Compute Engine 資源類型 (例如 gce_instance 和 gce_network)，您會看到資源名稱，資源 ID 則顯示為副文字。舉例來說，如果是 gce_instance 資源類型，您會看到 VM 名稱和 VM ID。資源名稱可協助您找出正確的資源 ID，並據此建立查詢。

依時間範圍查看記錄檔

如要顯示特定時間範圍內寫入的記錄，有兩種做法：

  1. 使用時間範圍選取器。
  2. 在查詢編輯器欄位中加入時間戳記運算式。

使用時間範圍選取器

預設時間範圍為一小時，但您可以從預設時間選項中選取，指定自訂開始和結束時間，或使用時間範圍選取器，將時間範圍集中在特定時間戳記周圍。舉例來說，如要查看過去一週的資料，請從時間範圍選擇器選取「過去 1 週」。

您也可以使用時間範圍選擇器設定時區偏好設定。

在查詢編輯器欄位中加入時間戳記運算式

如要直接在查詢編輯器欄位中新增時間戳記運算式，請使用記錄查詢語言。

如果查詢編輯器欄位包含含有時間戳記的運算式，時間範圍選取器就會停用，且查詢會使用時間戳記運算式做為時間範圍限制。如果查詢未使用時間戳記運算式，則查詢會使用時間範圍選取器做為時間範圍限制。

使用記錄查詢語言撰寫進階查詢

您可以使用記錄查詢語言，在記錄檔探索工具的查詢編輯器欄位中建構更進階的查詢：

  1. 如果「查詢」窗格中沒有顯示查詢編輯器欄位，請啟用「顯示查詢」。

  2. 直接在查詢編輯器欄位中輸入查詢運算式。

    如果您在搜尋欄位中新增任何搜尋字詞，或在篩選器選單中選取任何參數，這些字詞/參數也會顯示在查詢編輯器欄位中，並做為查詢運算式的一部分進行評估。

  3. 查看查詢後，按一下「執行查詢」。

    符合查詢條件的記錄會列於「Query results」(查詢結果) 窗格下方。「直方圖」和「記錄檔欄位」窗格也會根據查詢運算式調整。

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

使用近期查詢

執行任何查詢時，系統會將查詢新增至 查詢庫，其中包含 30 天內最後 10,000 個不重複的查詢。

如要查看近期查詢，請選取主要工具列中的「查詢資料庫」按鈕。如要處理近期查詢，您可以採取下列做法：

  • 串流：如要執行查詢並串流結果，請選擇這個選項。
  • 「執行」：選擇這個選項即可執行查詢。

  • 「更多選項」： 可查看查詢運算式，並選擇執行查詢或將查詢儲存至「已儲存」查詢清單。你也可以直接選取查詢，取得這些選項。

    如要儲存查詢，請按照下列步驟操作：

    1. 按一下 [儲存]。系統會開啟「儲存查詢」對話方塊。

    2. 填寫下列欄位：

      • 名稱 (必填)：為查詢命名。名稱長度不得超過 64 個字元。
      • 「說明」 (選填)：提供說明，協助識別查詢目的。
      • 包含摘要欄位 (選用)：啟用「包含摘要欄位」，然後輸入要顯示的摘要欄位。
      • 截斷摘要欄位 (選用)：啟用「截斷摘要欄位」，然後選取要截斷的字元數，以及要從欄位開頭還是結尾截斷。

    3. 按一下「儲存查詢」。查詢現在會顯示在已儲存的查詢清單中。

你也可以排序及篩選近期查詢內容；篩選器會比對查詢運算式中的文字。

儲存及共用查詢

儲存的查詢可讓您儲存查詢運算式，有助於更一致且有效率地探索記錄。Logs Explorer 具有查詢程式庫，可供您存取已儲存的查詢。您也可以使用 Logging API 方法 savedQueries.create 儲存查詢。

您可以儲存查詢，將查詢設為私人，只有您能查看，也可以與 Google Cloud 專案的其他成員共用。查詢共用後，您就不再是查詢擁有者，專案中具備必要權限的任何成員都能存取查詢。

主控台

如要儲存您在查詢編輯器欄位中建立的查詢運算式，請按照下列步驟操作：

  1. 按一下「Query」(查詢) 窗格中的「Save」(儲存)。「儲存查詢」對話方塊隨即開啟，查詢編輯器欄位中會顯示查詢運算式。

  2. 填寫下列欄位：

    • 名稱 (必填)：為查詢命名。名稱長度不得超過 64 個字元。
    • 「說明」 (選填)：提供說明，協助識別查詢目的。
    • 加入自訂摘要欄位 (選用)：啟用「加入摘要欄位」，然後輸入要顯示的摘要欄位。
    • 截斷摘要欄位 (選用)：啟用「截斷摘要欄位」，然後選取要截斷的字元數，以及要從欄位開頭還是結尾截斷。
    • 與專案共用：視需要啟用「與專案共用」，與 Google Cloud 專案的其他成員共用查詢。

  3. 按一下「儲存查詢」，已儲存的查詢會顯示在「已儲存」分頁下方的清單中。

如要執行已儲存的查詢，請按一下「執行」。如要執行查詢並串流結果，請按一下「串流」。

如要修改已儲存的查詢，請依序選取「更多選項」和「編輯」。您也可以選取查詢、進行修改，然後儲存修改後的查詢。

如要刪除已儲存的查詢，請選取「更多選項」圖示 ，然後選取「刪除」圖示 。

您也可以排序及篩選已儲存的查詢，篩選器會比對查詢運算式中的文字。

API

如要使用 Logging API 儲存查詢，請使用 savedQueries.create 方法。如要進一步瞭解這個方法、參數和回應資料，請參閱 savedQueries.create 的參考頁面。

您可以使用方法參考資料頁面上的 APIs Explorer 小工具，執行 savedQueries.create 方法。如果是記錄檔探索工具查詢，您必須指定 loggingQuery 欄位。以下範例說明要求主體範例，其中包含 SavedQuery 的例項：

{
  "parent": "projects/my-project/locations/global"
  "savedQueryId": "compute-query"
  {
    "displayName": "compute-admin-activity-query",
    "description": "Queries for Compute Engine Admin Activity logs.",

    "loggingQuery":
      {
        "filter": resource.type="gce_instance" AND log_id("cloudaudit.googleapis.com/activity"),
      },
    "visibility": "PRIVATE"
  }
}

如要與其他 Google Cloud 專案成員共用查詢，請在 visibility 欄位中指定 SHARED 值。

查看已儲存的查詢

如要查看私人查詢和與其他成員共用的查詢，請按一下 Google Cloud 專案中的「查詢資料庫」按鈕：

主控台

  1. 前往 Google Cloud 控制台的「Logs Explorer」頁面：

    前往「Logs Explorer」(記錄檔探索工具)

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

  2. 選取要查看記錄的 Google Cloud 專案或其他 Google Cloud資源。

  3. 按一下「查詢資料庫」按鈕，然後按一下「已儲存」。

你可以按任一標題排序表格。「瀏覽權限」欄會指出查詢是共用或私人：

  • 已共用：與Google Cloud 專案的其他成員共用的查詢。
  • 私人：您儲存的查詢，只有您能看到。

API

您可以使用 Logging API，透過 savedQueries.list 方法查看私密和共用查詢。

舉例來說，下列要求內容會列出所有共用的記錄檔探索工具查詢，並使用萬用字元位置 ID：

{
  "parent": "name": projects/PROJECT_ID/locations/-
  "visibility": "SHARED"
  "filter": "explorer"
}

使用建議的查詢

記錄檔會根據專案的脈絡資訊 (例如您使用的產品) 生成建議查詢。Google Cloud Google Cloud 建議查詢可協助您找出問題，並深入瞭解系統的整體健康狀態。舉例來說，如果系統偵測到您使用 Google Kubernetes Engine，Logging 可能會建議查詢，找出容器的所有錯誤記錄。

如要查看及執行建議查詢，請按一下「查詢資料庫」按鈕，然後點選「建議」。在「建議」分頁中，您可以選擇：

  • 串流：如要執行查詢並串流結果，請選擇這個選項。
  • 「執行」：選擇這個選項即可執行查詢。

  • 更多選項： 可查看查詢運算式的詳細資料，並選擇執行或儲存查詢。你也可以直接選取查詢，取得這些選項。

    如要查看建議查詢的詳細資料，請執行下列任一操作：

    • 選取查詢的資料列。

    • 按一下「更多」圖示 ，然後選取「查看」。「查詢詳細資料」對話方塊隨即開啟。

    在「查詢詳細資料」對話方塊中，您會看到查詢和「執行」、「串流」或「另存為」選項：

    • 如要儲存查詢，請按照下列步驟操作：

      1. 按一下 [Save query] (儲存查詢)。
      2. 填寫「儲存查詢」對話方塊中的欄位。

      編輯後的查詢會顯示在「已儲存」清單中，您可以在日後選擇執行查詢。

    • 如要立即執行查詢，請按一下「執行」。查詢會執行並顯示在查詢編輯器欄位中。

    • 如要立即執行查詢並串流結果，請按一下「串流」。

    • 如要關閉對話方塊並返回建議查詢清單，請按一下「關閉」。

請注意下列預期行為：

  • 連續載入網頁時，系統可能不會以相同順序顯示相同查詢。
  • 您可能會看到零個建議的查詢。
  • 有時執行建議的查詢會傳回零個記錄。

從資料庫選取查詢

記錄功能提供以常見用途和 Google Cloud 產品為依據的查詢程式庫。在時間緊迫的疑難排解工作階段中，這些查詢可協助您有效率地尋找記錄，並探索記錄，進一步瞭解可用的 Logging 資料。

如要查看及執行程式庫的查詢，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Logs Explorer」頁面：

    前往「Logs Explorer」(記錄檔探索工具)

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

  2. 選取要查看記錄的 Google Cloud 專案或其他 Google Cloud資源。

  3. 按一下「查詢資料庫」按鈕。您會看到可用的查詢類別，以及根據 Google Cloud產品劃分的查詢子集。如要縮小顯示的查詢範圍，請按一下任一產品。

    您也可以使用搜尋欄位，依類別、說明或查詢運算式的內容搜尋可用的查詢。

  4. 如要查看查詢運算式，請執行下列任一操作：

    a. 按一下查詢的資料列。

    b. 按一下「更多」圖示 ，然後選取「查看」。

  5. 在「查詢詳細資料」對話方塊中，您會看到查詢和「執行」、「串流」或「另存為」選項：

    • 如要儲存查詢，請按照下列步驟操作：

      1. 按一下 [Save query] (儲存查詢)。
      2. 填寫「儲存查詢」對話方塊中的欄位。

      編輯後的查詢會顯示在「已儲存」清單中，您可以在日後選擇執行查詢。

    • 如要立即執行查詢，請按一下「執行」。查詢會執行並顯示在查詢編輯器欄位中。

    • 如要立即執行查詢並串流結果，請按一下「串流」。

    • 如要關閉對話方塊並返回建議查詢清單，請按一下「關閉」。

後續步驟