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

使用 gcloud CLI 寫入記錄項目

記錄功能支援含有結構化和非結構化資料的記錄項目。結構化資料包含 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 列出記錄項目

您可以使用 gcloud CLI 從 Cloud Logging 擷取記錄項目並顯示。舉例來說，如要擷取並顯示資源類型為 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參考文件。

在 Logs Explorer 中查看記錄項目

如要在 Cloud de Confiance 控制台中查看記錄項目，可以使用 Logs Explorer。大多數 Cloud de Confiance 專案都會儲存大量記錄，您可以撰寫查詢來選取特定記錄項目。

如要使用 Logs Explorer 查看您寫入的記錄項目，請執行下列操作：

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

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

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

   確認已在導覽列中選取 Cloud de Confiance 專案 Cloud de Confiance by S3NS。如有需要，請使用 Cloud de Confiance 專案下拉式選單 選取 Cloud de Confiance 專案。

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

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

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

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

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

在 Logs Explorer 中查詢記錄項目

您可以使用查詢編輯器查詢記錄項目，並透過鍵和值查詢結構化記錄。舉例來說，如要顯示所有包含文字 simple 的記錄項目，請執行下列操作：

1. 前往 Cloud de Confiance 控制台的 segment「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。

Logs Explorer 也提供已儲存、建議和最近的查詢。如要進一步瞭解查詢，請參閱「透過 Logs Explorer 建構查詢」。

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

疑難排解

• 如果發生錯字或使用不明的欄位名稱，gcloud CLI 指令會完成，但會顯示無效引數訊息。舉例來說，如果您忘記在 resource.type 中加上句號，就會發生下列錯誤：

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

• 如果 Cloud Logging 未獲得必要的存取權限，gcloud CLI 指令會完成，但會顯示「permission denied」訊息。舉例來說，如果 Compute Engine VM 執行個體是使用預設 API 設定，list 指令就會完成，但會顯示權限遭拒錯誤：

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

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

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