使用 Python 指令碼寫入及查詢記錄項目

開始使用

您可以使用 Cloud Shell 環境或一般 Linux 環境完成這項快速入門導覽課程。Cloud Shell 已預先安裝 Python。

複製原始碼

如要為本快速入門導覽課程設定 Cloud Shell，請執行下列操作：

1. 複製 GitHub 專案 python-logging：

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

   目錄 samples/snippets 包含本快速入門導覽課程中使用的兩個指令碼：

   • snippets.py 可讓您管理記錄中的項目。
   • export.py 可讓您管理記錄匯出作業。

2. 切換至 snippets 目錄：

   cd logging/samples/snippets
   

寫入記錄項目

snippets.py 指令碼會使用 Python 用戶端程式庫，將記錄項目寫入 Logging。在指令列指定 write 選項時，指令碼會寫入下列記錄項目：

• 具有非結構化資料且未指定任何嚴重性等級的項目。
• 具有非結構化資料且嚴重性等級為 ERROR 的項目。
• 具有 JSON 結構化資料且未指定任何嚴重性等級的項目。

如要將新的記錄項目寫入記錄檔 my-log，請使用 write 選項執行 snippets.py 指令碼：

python snippets.py my-log write

查看記錄項目

如要在 Cloud Shell 中查看記錄項目，請執行 snippets.py 指令碼並加上 list 選項：

python snippets.py my-log list

指令完成後，會傳回下列結果：

Listing entries for logger my-log:
* 2025-11-13T16:05:35.548471+00:00: Hello, world!
* 2025-11-13T16:05:35.647190+00:00: Goodbye, world!
* 2025-11-13T16:05:35.726315+00:00: {u'favorite_color': u'Blue', u'quest': u'Find the Holy Grail', u'name': u'King Arthur'}

如果結果未顯示任何項目，請重試指令。Logging 需要一些時間才能接收及處理記錄項目。

您也可以使用 Logs Explorer 查看寫入的記錄項目。詳情請參閱「使用 Logs Explorer 查看記錄檔」。

刪除記錄項目

如要刪除記錄 my-log 中的所有記錄項目，請執行 snippets.py 指令碼，並加上 delete 選項：

python snippets.py my-log delete

指令完成後，會傳回下列結果：

Deleted all logging entries for my-log。

路徑記錄

在本節中，執行以下操作：

• 建立 Cloud Storage bucket，做為資料的目的地。
• 建立將新記錄項目複製到目的地的接收器。
• 更新 Cloud Storage bucket 的權限。
• 將記錄項目寫入 Logging。
• 您可以視需要驗證 Cloud Storage bucket 的內容。

建立目的地

本快速入門導覽課程的匯出目的地是 Cloud Storage bucket。如要建立 Cloud Storage bucket，請按照下列步驟操作：

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

   前往「Buckets」

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

2. 按一下「建立值區」。
3. 輸入 bucket 的名稱。本快速入門導覽課程使用 myloggingproject-1 這個名稱。
4. 在「位置類型」部分，選取「區域」，系統會選取延遲時間最低的 bucket 位置。
5. 在「設定預設級別」部分選取「Standard」。
6. 在「存取控管」部分，選取「精細」。
7. 在「保護工具」部分選取「無」，然後點選「建立」。

建立接收器

接收器是一項規則，可決定 Logging 是否將新收到的記錄項目轉送至目的地。接收器有下列三種屬性：

• 名稱
• 目的地
• 篩選器

如要進一步瞭解接收器，請參閱「關於記錄檔接收器」。

如果新收到的記錄項目符合查詢條件，該記錄項目就會轉送至目的地。

export.py 指令碼會使用 Python 用戶端程式庫建立、列出、修改及刪除接收器。如要建立接收器 mysink，將嚴重性至少為 INFO 的所有記錄項目匯出至 Cloud Storage bucket myloggingproject-1，請執行下列指令：

python export.py create mysink myloggingproject-1 "severity>=INFO"

指令碼會傳回下列內容：

Created sink mysink

如要查看接收器，請執行 export.py 指令碼並加上 list 選項：

python export.py list

指令碼會傳回下列內容：

mysink: severity>=INFO -> storage.googleapis.com/myloggingproject-1

更新目的地權限

使用 export.py 指令碼建立接收器時，目的地 (在本例中為 Cloud Storage bucket) 的權限不會遭到修改。您必須變更 Cloud Storage bucket 的權限設定，授予寫入接收器的權限。如要瞭解服務帳戶、存取權範圍和 Identity and Access Management 角色，請參閱「服務帳戶」。

如要更新 Cloud Storage bucket 的權限，請按照下列步驟操作：

1. 識別接收器的「Writer Identity」(寫入者身分)：

   1. 前往 Google Cloud 控制台的「Log Router」(記錄檔路由器) 頁面：

      前往「Log Router」(記錄檔路由器)

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

      您會看到接收器的摘要表格。

   2. 在表格中找到接收器，依序選取 more_vert「Menu」(選單) 和「View sink details」(查看接收器詳細資料)。

   3. 將寫入者身分複製到剪貼簿。

2. 前往 Google Cloud 控制台的「Bucket」頁面：

   前往「Buckets」

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

3. 如要開啟詳細資料視圖，請按值區名稱。

4. 選取「權限」，然後按一下「授予存取權」。

5. 將寫入者身分貼到「New principals」(新增主體) 方塊中。從寫入者身分位址中移除 serviceAccount: 前置字元。

6. 將「Role」(角色) 設為 Storage Admin，然後點選「Save」(儲存)。

詳情請參閱「設定目的地權限」。

驗證接收器

如要驗證接收器和目的地是否設定正確，請執行下列操作：

1. 將新的記錄項目寫入記錄檔 my-log：

   python snippets.py my-log write
   

2. 查看 Cloud Storage bucket 的內容：

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

      前往「Buckets」

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

   2. 如要開啟詳細資料視圖，請按值區名稱。詳細資料視圖會列出包含資料的資料夾。如果 bucket 中沒有資料，系統會顯示下列訊息：

      There are no live objects in this bucket.

      如「延遲抵達的記錄項目」一節所述，目的地可能需要 2 或 3 小時才會顯示第一批項目，或通知您設定錯誤。

      bucket 收到資料後，詳細資料檢視畫面會顯示類似以下的結果：

      

   3. 每個資料夾中的資料都會整理為一系列的資料夾，頂層資料夾會標示記錄名稱，然後依序標示年、月和日。如要查看接收器匯出的資料，請按一下資料夾名稱 my-log，然後依序點選年、月和日等子資料夾，直到找到結尾為 json 的檔案為止：

      

   4. JSON 檔案包含匯出至 Cloud Storage bucket 的記錄項目。點選 JSON 檔案名稱即可查看內容。內容類似：

       {"insertId":"yf1cshfoivz48",
       "logName":"projects/loggingproject-222616/logs/my-log",
       "receiveTimestamp":"2018-11-15T23:06:14.738729911Z",
       "resource":{"labels":{"project_id":"loggingproject-222616"},"type":"global"},
       "severity":"ERROR",
       "textPayload":"Goodbye, world!",
       "timestamp":"2018-11-15T23:06:14.738729911Z"}
      

      由於 ERROR 的嚴重性等級高於 INFO 的嚴重性等級，因此包含字串「"Goodbye, world!"」的記錄項目會匯出至接收器目的地。其他寫入的記錄項目未匯出至目的地，因為其嚴重性等級設為預設值，而預設嚴重性等級低於 INFO。

疑難排解

Cloud Storage bucket 可能因下列原因而空白：

• bucket 尚未收到資料。 目的地可能需要 2 或 3 小時才會顯示第一批項目，或通知您設定錯誤。詳情請參閱「延遲抵達的記錄項目」。

• 設定有誤。在這種情況下，您會收到類似下列主旨行的電子郵件訊息：

   [ACTION REQUIRED] Logging export config error in myloggingproject.

  電子郵件內文會說明設定問題。舉例來說，如果您未更新目的地權限，電子郵件會列出下列錯誤代碼：

   bucket_permission_denied

  如要修正這個特定情況，請參閱本頁的「更新目的地權限」一節。

• 建立接收器後，未寫入任何記錄項目。接收器僅適用於新抵達的記錄項目。如要修正這種情況，請寫入新的記錄項目：

   python snippets.py my-log write