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

開始使用

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

複製原始碼

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

1. 複製 GitHub 專案 python-logging：

     git clone https://github.com/googleapis/python-logging
   

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

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

2. 切換至 snippets 目錄：

     cd python-logging/samples/snippets
   

寫入記錄項目

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

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

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

python snippets.py my-log write

查看記錄項目

如需查看 Cloud Shell 中的記錄項目，請以 list 選項執行 snippets.py 指令碼：

python snippets.py my-log list

指令執行完畢並出現以下結果：

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

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

您也可以使用記錄探索工具查看記錄項目。詳情請參閱「使用記錄檔探索工具查看記錄檔」。

刪除記錄項目

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

python snippets.py my-log delete

指令執行完畢並出現以下結果：

Deleted all logging entries for my-log。

路徑記錄

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

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

建立目的地

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

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

   前往「Buckets」(值區)

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

2. 點選「建立值區」。
3. 輸入 bucket 的名稱。
4. 在「位置類型」部分，選取「區域」，系統會選取延遲時間最短的 bucket 位置。
5. 在「預設儲存空間級別」部分，選取「Standard」。
6. 在「Access control」(存取控管) 的部分選取「Fine-grained」(精細)。
7. 在「保護工具」部分選取「無」，然後點按「建立」。

本快速入門導覽課程使用的 Cloud Storage 值區名稱為myloggingproject-1。

建立接收器

接收器是一種規則，用於判斷 Logging 是否將新抵達的記錄項目轉送至目的地。接收器有下列三種屬性：

• 名稱
• 目的地
• 篩選器

如要進一步瞭解接收器，請參閱「接收器」。

如果新抵達的記錄項目符合查詢條件，則會將該記錄項目傳送至目的地。

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

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

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

python export.py list

指令碼會傳回下列內容：

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

更新目的地權限

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

如要更新 Cloud Storage 值區權限：

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

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

      前往「記錄檔路由器」

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

      畫面上會顯示水槽的摘要表格。

   2. 在表格中找出接收器，選取「選單」more_vert，然後選取「查看接收器詳細資料」。

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

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

   前往「Buckets」(值區)

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

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

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

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

6. 將「角色」設為 Storage Object Creator，然後按一下「儲存」。

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

驗證接收器

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

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

   python snippets.py my-log write
   

2. 查看 Cloud Storage bucket 的內容：

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

      前往「Buckets」(值區)

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

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

      There are no live objects in this bucket.

      如延遲抵達的記錄項目所述，可能需要 2 或 3 個小時才會看到第一批項目出現在目的地，或收到設定錯誤通知。

      值區收到資料後，詳細資料視圖會顯示類似下方的結果：

      

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

      

   4. JSON 檔案包含已匯出至 Cloud Storage 值區的記錄項目。按一下 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 值區沒有任何物件：

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

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

   [ACTION REQUIRED] Logging export config error in myloggingproject.

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

   bucket_permission_denied

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

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

   python snippets.py my-log write