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

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

您也可以在「Logs Explorer」(記錄檢視器) 頁面中儲存查詢，或是使用 Logging API 方法 savedQueries.create。

事前準備

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

執行下列其中一個步驟：

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

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

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

建構查詢

如要使用 Trusted Cloud 主控台建立查詢，請按照下列步驟操作：

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

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

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

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

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

    「Query」窗格提供多種建構及執行查詢運算式的做法：

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

搜尋記錄檔欄位中的文字

如要搜尋所有記錄檔欄位中的文字，並找出所有相符的記錄項目，請在「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 相符，因為搜尋並未沿著符號邊界執行。

如要查看查詢運算式中的搜尋字詞，請啟用「Show query」(顯示查詢)。

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

布林運算子

系統會將搜尋欄位項目轉換為布林運算式，指定所選 Trusted 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」窗格中的篩選器選單，將資源、記錄名稱、記錄嚴重程度和相關參數新增至查詢編輯器欄位。這些選項對應至 Logging 中所有記錄的 LogEntry 欄位。

「Resource」和「Log name」選單中的選項，是取自 Cloud Logging 儲存的記錄項目。

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

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

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

  2. 調整篩選器參數。

  3. 按一下 [套用]。您會在查詢編輯器欄位中看到參數。

    如要查看查詢運算式中的搜尋字詞，請啟用「Show query」(顯示查詢)。

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

對於某些 Compute Engine 資源類型 (例如 gce_instance 和 gce_network)，您會看到資源名稱，其中包含資源 ID 做為副標題。舉例來說，如果是 gce_instance 資源類型，您會在 VM ID 旁看到 VM 名稱。資源名稱可協助您找出正確的資源 ID，以便建立查詢。

依時間範圍查看記錄檔

您可以透過兩種方式，查看在特定時間範圍內寫入的記錄：

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

使用時間範圍選取器

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

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

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

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

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

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

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

  1. 如果您在「查詢」窗格中找不到查詢編輯器欄位，請啟用「顯示查詢」。

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

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

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

    符合查詢的記錄會列於「Query results」窗格下方。「Histogram」和「Log fields」窗格也會根據查詢運算式調整。

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

使用近期查詢

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

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

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

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

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

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

    2. 填寫下列欄位：

      • 名稱 (必填)：提供查詢的名稱。名稱長度不得超過 64 個半形字元。
      • 說明 (選用)：提供說明，協助識別查詢的用途。
      • 包含摘要欄位 (選用)：啟用「包含摘要欄位」，然後輸入要顯示的摘要欄位。
      • 截斷摘要欄位 (選用)：啟用「截斷摘要欄位」，並選取要截斷的字元數量，以及截斷字元是否會出現在欄位的開頭或結尾。

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

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

儲存及共用查詢

儲存查詢可讓您儲存查詢運算式，以便更有效率地探索記錄檔。記錄檔探索工具提供查詢程式庫，可讓您存取已儲存的查詢。您也可以使用 Logging API 方法 savedQueries.create 儲存查詢。

您可以儲存查詢，讓查詢保持私密狀態，只有您能查看，也可以與 Trusted Cloud 專案的其他成員分享查詢。分享查詢後，查詢就不再屬於您，專案中任何擁有必要權限的成員都能存取查詢。

主控台

如要儲存在查詢編輯器欄位中建立的查詢運算式，請執行下列操作：

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

  2. 填寫下列欄位：

    • 名稱 (必填)：提供查詢的名稱。名稱長度不得超過 64 個半形字元。
    • 說明 (選用)：提供說明，協助識別查詢的用途。
    • 加入自訂摘要欄位 (選用)：啟用「加入摘要欄位」，然後輸入要顯示的摘要欄位。
    • 截斷摘要欄位 (選用)：啟用「截斷摘要欄位」，並選取要截斷的字元數量，以及截斷字元是否會出現在欄位的開頭或結尾。
    • 與專案共用：您可以選擇啟用「與專案共用」，與 Trusted Cloud 專案的其他成員共用查詢。

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

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

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

如要刪除已儲存的查詢，請依序選取 「更多選項」和 「刪除」。

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

API

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

以下範例說明含有 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"
  }
}

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

查看已儲存的查詢

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

主控台

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

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

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

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

  3. 按一下 「查詢媒體庫」按鈕，然後點選「已儲存」。

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

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

API

您可以使用 Logging API 搭配 savedQueries.list 方法，查看私人和共用查詢。

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

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

使用建議的查詢

記錄功能會根據Trusted Cloud 專案的背景資訊 (例如您使用的 Trusted Cloud 產品)，產生建議查詢。建議查詢可協助您找出問題，並提供系統整體健康狀況的洞察資料。舉例來說，如果系統偵測到您使用 Google Kubernetes Engine，記錄功能可能會建議您執行查詢，找出容器的所有錯誤記錄。

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

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

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

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

    • 選取查詢的資料列。

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

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

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

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

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

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

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

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

請注意下列預期行為：

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

從媒體庫中選取查詢

記錄功能會根據常見用途和 Trusted Cloud 產品提供查詢程式庫。這些查詢可協助您在時間敏感的疑難排解工作階段中，有效地尋找記錄，並探索記錄檔，進一步瞭解可用的記錄資料。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

後續步驟