使用 gcloud CLI 寫入及查詢記錄項目

本文介紹 Cloud Logging 的部分功能，並說明如何執行下列操作：

  • 使用 Google Cloud CLI 寫入記錄項目。
  • 使用 gcloud CLI 列出記錄項目。
  • 使用 Logging API 列出記錄項目。
  • 使用記錄檔探索工具查看及查詢記錄項目。

事前準備

您必須擁有已啟用計費功能的 Google Cloud 專案，才能完成此快速入門導覽課程。如果您沒有 Google Cloud 專案，或是專案尚未啟用計費功能，請執行下列步驟： Google Cloud

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the Google Cloud CLI.

  3. 如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  4. 如要初始化 gcloud CLI，請執行下列指令： 

    gcloud init

  5. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Install the Google Cloud CLI.

  8. 如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  9. 如要初始化 gcloud CLI，請執行下列指令： 

    gcloud init

  10. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  11. Verify that billing is enabled for your Google Cloud project.

    12. 使用 gcloud CLI 寫入記錄項目

    Logging 可支援包含結構化和非結構化資料的記錄項目。結構化資料包含 JSON 資料結構；例如 {"weather": "partly cloudy"}。非結構化資料是字元字串；例如 "A simple entry"。

    在接下來的步驟中，您將使用 gcloud CLI 寫入含有非結構化資料的記錄項目，以及含有結構化資料的記錄項目。gcloud CLI 提供 Cloud Logging API 的指令列介面。

    1. 將含有非結構化資料的記錄項目寫入 my-test-log 記錄，請執行 gcloud logging write 指令：

      gcloud logging write my-test-log "A simple entry."

      指令完成後，您會看到以下訊息：Created log entry。

    2. 將含有結構化資料的記錄項目寫入 my-test-log 記錄：

      gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'

      使用結構化資料撰寫記錄項目時，必須加入 --payload-type=json。如果您省略這個欄位，Logging 會將酬載解讀為非結構化資料。

    如果記錄 my-test-log 不存在，則 Logging 會在收到記錄項目時建立記錄。

    使用 gcloud CLI 列出記錄項目

    您可以從 Logging 擷取記錄項目，並使用 gcloud CLI 顯示這些項目。舉例來說，如要擷取並顯示資源類型為 global 的記錄項目，請執行下列指令：

    gcloud logging read "resource.type=global"

    指令會傳回類似以下的結果：

    ---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

    如要瞭解如何讀取記錄，請參閱 gcloud logging read 參考說明文件。

    使用 API Explorer 列出記錄項目

    如要在不編寫任何程式碼的情況下執行 Logging API 方法，請參閱「使用 API Explorer」。如要從 Logging 讀取記錄項目清單，請按照下列步驟操作：

    1. 前往 entries.list API 方法的 API 參考資料頁面：

      前往 entries.list API 頁面

    2. 設定並執行 API 指令：

      1. 將下列文字中的 PROJECT_ID 替換為：

        "resourceNames": [
"projects/PROJECT_ID"
],
"filter": "resource.type=global",
"orderBy": "timestamp desc"

      2. 複製上一個步驟中更新的文字，然後貼到 APIs Explorer 的「Request body」(要求主體) 欄位。

      3. 按一下 [Execute] (執行)。

      方法會傳回類似以下的回應：

      {
  "entries": [
    {
      "textPayload": "A simple entry",
      "insertId": "vd4m1if7h7u1a",
      "resource": {
        "type": "global",
        "labels": {
          "project_id": "myloggingproject"
        }
      },
      "timestamp": "2018-11-01T18:39:19.718100792Z",
      "logName": "projects/myloggingproject/logs/my-test-log",
      "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
    },
    {
      "insertId": "jpj9zjf73t1mn",
      "jsonPayload": {
        "message": "My second entry",
        "weather": "partly cloudy"
      },
      "resource": {
        "type": "global",
        "labels": {
          "project_id": "myloggingproject"
        }
      },
      "timestamp": "2018-11-01T18:39:31.114507977Z",
      "logName": "projects/myloggingproject/logs/my-test-log",
      "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
    }
  ]
}

    在記錄檔探索工具中查看記錄項目

    如要在 Google Cloud 控制台中查看記錄項目，可以使用記錄檔探索工具。大多數 Google Cloud 專案都會儲存大量記錄，您可以撰寫查詢來選取特定記錄項目。

    如要使用記錄檔探索工具查看您寫入的記錄項目，請按照下列步驟操作：

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

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

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

      確認已在導覽列中選取 Google Cloud 專案 Google Cloud。如有必要，請使用 Google Cloud 專案下拉式清單選取 Google Cloud 專案。

    2. 在「Resource」(資源) 選單中，選取「Global」(全域)。

      如果沒看到「Global」選單選項，或找不到記錄項目，請稍候幾分鐘，然後重新整理頁面。Logging 可能需要幾分鐘的時間才能接收記錄項目。

    3. 如要查看記錄項目的詳細資料，請按一下該項目的「選單」。

      第一筆記錄項目的資料儲存在 textPayload。第二個記錄項目包含儲存在 jsonPayload 中的結構化資料。結構化酬載包含 message 和 weather 索引鍵。

    如要瞭解記錄項目的資料格式，請參閱 LogEntry 類型。

    在記錄檔探索工具中查詢記錄項目

    您可以使用查詢編輯器查詢記錄項目，並依索引與項目值篩選具有結構化記錄的記錄項目。舉例來說，如要顯示所有含有文字 simple 的記錄項目，請執行下列操作：

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

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

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

    2. 在「Resource」(資源) 選單中，選取「Global」(全域)。

    3. 在查詢編輯器中，輸入以引號括住的字串 simple。 記錄顯示畫面只會顯示 A simple entry. 記錄項目。

    4. 查看記錄之後，請移除您新增的查詢字串，然後按一下「Run query」(執行查詢)。兩個記錄項目都會重新顯示在顯示畫面中。

    如要顯示具有結構化資料的所有記錄項目，且結構化資料中已有 weather 索引，同時索引的 value 欄位包含 partly，請執行下列步驟：

    1. 查詢編輯器包含 resource.type="global" 這一行。 輸入下列指令：

      jsonPayload.weather:partly

    2. 按一下 [Run query] (執行查詢)。結果會產生單一記錄項目 My second entry。

    記錄檔探索工具也提供已儲存、建議和最近的查詢。 如要進一步瞭解查詢，請參閱「在記錄檔探索工具中建構查詢」。

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

    疑難排解

    • 若存在打字錯誤與不明的欄位名稱，會導致 gcloud CLI 指令在完成時顯示引數無效的訊息。舉例來說，如果您漏掉 resource.type 中的句點，會導致發生錯誤：

       ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.

    • 若未授予 Cloud Logging 必要的存取權限，gcloud CLI 指令會在完成時顯示權限遭拒的訊息。舉例來說，如果使用預設 API 設定來設定 Compute Engine VM 執行個體，list 指令會在完成時顯示權限遭拒的錯誤：

       ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.

      如要修正這個問題，請修改 Compute Engine VM 執行個體權限，授予 Cloud Logging 讀取權限，方法如下：

      1. 前往 VM 執行個體的「VM instance details」(VM 執行個體詳細資料) 頁面。 按一下「停止」。這個動作可能需要一兩分鐘的時間才能完成。
      2. 如要修改設定，請按一下 [Edit] (編輯)。
      3. 搜尋標頭「Cloud API 存取權範圍」，然後點選「詳細資料」，即可顯示每個 API 的設定。將項目從 Cloud Logging API 變更為「Full」(完整)。然後按一下 [儲存]。
      4. 如要重新啟動您的 VM 執行個體，請按一下 [Start] (啟動)。經過一段時間後，您的 VM 即準備好可供使用。

    • 當 API Explorer 無法完成您的指令，或需要其他授權時，其會顯示一則訊息或一個錯誤代碼：

      • 200 回應碼且沒有項目：如果顯示 nextPageToken 訊息，表示 API Explorer 沒有時間完成搜尋。將 pageToken 新增至您的要求，將值設為與 nextPageToken 索引指定的值完全相同，接著重試指令。
      • 400 回應碼：查詢值無效。舉例來說，如果您將 global 拼錯為 gloobal，則訊息會是 Unsupported resource type: gloobal。
      • 404 回應碼：專案 ID 無效。檢查專案 ID 的拼寫。
      • 系統可能會要求您登入Google Cloud 專案，並允許 API Explorer 存取您的帳戶。

    清除所用資源

    如要避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請刪除含有這些資源的 Google Cloud 專案。

    1. (選用) 如要刪除您建立的記錄項目，請執行下列gcloud指令：

      gcloud logging logs delete my-test-log

      如果您不刪除記錄項目，這些項目將會到期並遭到移除。 如需保留資訊，請參閱「配額與限制」一文。

    後續步驟