使用 Python 的快速入門導覽課程

在本快速入門導覽課程中,您會執行 Python 程式以寫入、讀取、刪除及匯出記錄項目。

事前準備

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

    如果您沒有帳戶,請申請新帳戶

  2. 選取或建立 Google Cloud Platform 專案。

    前往「Manage resources」(管理資源) 頁面

  3. 請確認您已啟用 Google Cloud Platform 專案的計費功能。

    瞭解如何啟用計費功能

本快速入門導覽課程需要使用 Stackdriver Logging 與 Cloud Storage。使用這些資源會產生費用。完成本快速入門導覽課程後,您可以刪除已建立的資源,以避免持續進行計費。 詳情請參閱清除

入門指南

您可使用 Cloud Shell 環境或一般 Linux 環境完成此項快速入門導覽課程。

Cloud Shell

  1. Cloud Shell 中已預先安裝 Python 2.7 和 3.5 版。您不需要安裝或設定任何其他軟體。

  2. 開啟 Cloud Shell 並驗證專案配置:

    1. 從 GCP 主控台,按一下右上角的「Activate Cloud Shell」(啟用 Cloud Shell) 按鈕:

      啟用 Cloud Shell

      Cloud Shell 隨即會開啟視窗並顯示歡迎訊息:

      歡迎使用 Cloud Shell

    2. 歡迎訊息會回應已設定的專案 ID。如果這不是您要使用的專案,請在您用專案 ID 替換 [PROJECT_ID] 後執行以下指令:

       gcloud config set project [PROJECT_ID]
      

Linux

  1. 安裝及設定 Python。您可使用 Python 版本 2 或 3 進行此項快速入門導覽課程。詳情請參閱設定 Python 開發環境

  2. 為專案設定 Cloud Identity and Access Management 權限。請在下列步驟中為專案建立服務帳戶,然後產生及下載檔案至 Linux 工作站。

    1. 請在 GCP 主控台前往「IAM & admin」(身分與存取權管理及管理員) >「Service accounts」(服務帳戶)

      前往服務帳戶

    2. 請選擇快速入門導覽課程專案,然後按下「Create Service Account」(建立服務帳戶)

      • 輸入帳戶名稱。
      • 輸入帳戶說明。
      • 按一下 [Create] (建立)。
    3. 在「Service account permissions (optional)」(服務帳戶權限 (選用)) 窗格,請針對「Role」(角色) 由下拉式清單選擇「Logging Admin」(Logging 管理員)。按一下 [Continue] (繼續)。

    4. 略過授予使用者存取服務帳戶的選項。

    5. 建立金鑰檔案,並下載至您的工作站:

      • 請在「Create key (optional)」(建立金鑰 (選用)) 窗格中按下 [Create key] (建立金鑰)
      • 金鑰類型請選擇「JSON」,然後按下 [Create] (建立)。 之後會出現彈出式視窗,顯示類似以下所示內容的訊息:

        已儲存私密金鑰

    6. 請按 [Done] (完成) 以完成建立服務帳戶。

  3. 請在 Linux 工作站將環境變數 GOOGLE_APPLICATION_CREDENTIALS 設定為您的金鑰檔案路徑,以提供驗證憑證至應用程式。例如:

     export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/[FILE_NAME].json"
    

    此環境變數僅適用於您目前的殼層工作階段,所以如果您開啟新的工作階段,請再次設定變數。

複製原始碼

複製 GitHub 專案 python-docs-samples

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

目錄 python-docs-samples/logging/cloud-client 包含本快速入門導覽課程使用的兩個程式:

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

如需變更程式目錄,請執行下列指令:

cd python-docs-samples/logging/cloud-client

寫入記錄項目

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-list 中的記錄項目,請以 delete 選項執行 snippets.py 程式:

python snippets.py my-log delete

經過一段時間後,指令執行完畢並出現以下結果:

Deleted all logging entries for my-log

匯出記錄

Logging 可將記錄項目匯出至 Cloud Storage 值區、BigQuery 資料集與 Cloud Pub/Sub。如要進一步瞭解匯出,請參閱記錄匯出總覽

在本節中,執行以下操作:

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

建立目的地

本快速入門導覽課程的匯出目的地為 Cloud Storage 值區。如要建立 Cloud Storage 值區:

  1. 在 GCP 主控台資訊主頁中,前往「Storage」(儲存空間) >「Browser」(瀏覽器)

    前往瀏覽器

  2. 按一下 [Create Bucket] (建立值區)

  3. 選取值區的名稱。

  4. 選取 [Regional],並在「Location」(位置) 中選擇最接近的地理區域選項。

  5. 在「Access control model」(存取權控管模型) 中,選取 [Set object-level and bucket-level permissions] (設定物件層級和值區層級權限)

  6. 將所有其他設定保留為預設值。按一下 [Create] (建立)

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

建立接收器

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

  • 名稱
  • 目的地
  • 篩選器

如果新抵達的記錄項目符合篩選條件,則會將該記錄項目匯出至目的地。

export.py 程式使用 Python 用戶端程式庫建立、列表、修改及刪除接收器。如要建立 mysink 接收器,將嚴重性等級至少為 INFO 的所有記錄項目匯出至 Cloud Storage 值區 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 值區的權限設定,才能為接收器授予寫入權限。

如要更新 Cloud Storage 值區權限:

  1. 識別接收器的「寫入者身分」

    1. 前往「記錄檢視器」頁面:

      前往記錄檢視器頁面

    2. 選取「Exports」(匯出) 以查看接收器摘要,包括接收器的「寫入者身分」

  2. 從 GCP 主控台按一下 [Storage] (儲存空間) > [Browser] (瀏覽器)

    前往瀏覽器

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

  4. 選取「Permissions」(權限),然後點選 [Add members] (新增成員)

  5. 將「Role」(角色) 設定為 Storage Object Creator,然後輸入接收器的寫入者身分。

詳情請參閱目的地權限

驗證接收器

如要驗證接收器及目的地是否已正確設定:

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

    python snippets.py my-log write
    
  2. 查看 Cloud Storage 值區內容:

    1. 從 GCP 主控台按一下 [Storage] (儲存空間) > [Browser] (瀏覽器)

      前往瀏覽器

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

      There are no live objects in this bucket.

      已匯出記錄的可用性所述,可能需要 2 或 3 個小時才會看到第一批項目出現在目的地,或收到設定錯誤通知。

    3. 值區收到資料後,詳細資料視圖會顯示類似下方的結果:

      值區內容

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

      值區內容

    5. 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] Stackdriver Logging export config error in myloggingproject.

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

     bucket_permission_denied

    如要修正這個特定狀況,請參閱更新權限

  • 您並未在建立接收器後寫入記錄項目。接收器僅適用於新抵達的記錄項目。如要修正這種情況,請寫入新的記錄項目:

     python snippets.py my-log write
    

清除

如要避免系統向您的 GCP 帳戶收取您在快速入門導覽課程中所用資源的相關費用:

  1. (選用) 刪除您建立的記錄項目。如果您不刪除記錄項目,這些項目將會到期並遭到移除。 請參閱配額政策一文。如要刪除 my-log 記錄中的所有記錄項目,請執行以下指令:

     python snippets.py my-log delete
    
  2. 刪除專案或快速入門導覽課程資源。

    • 如要刪除專案,請從 GCP 主控台的「Project Info」(專案資訊) 窗格中按一下 [Go to project settings] (前往專案設定),然後按一下 [Shut down] (關閉)

    • 如要刪除快速入門導覽課程資源:

      1. 執行以下指令以刪除接收器:

        python export.py delete mysink
        
      2. 刪除 Cloud Storage 值區。前往 GCP 主控台,然後按一下 [Storage] (儲存空間) > [Browser] (瀏覽器)。勾選您的值區名稱旁的方塊,然後按一下 [Delete] (刪除)

後續步驟

  • 請參閱服務帳戶的詳細討論內容,以瞭解服務帳戶、存取範圍及 Cloud Identity and Access Management 角色。
  • 如要深入瞭解記錄檢視器,請參閱記錄檢視器
  • 請參閱匯出記錄,進一步瞭解如何將記錄項目匯出至 Cloud Storage、BigQuery 及 Cloud Pub/Sub。
  • 如要瞭解如何在 Stackdriver Logging 中收集來自虛擬機器執行個體的記錄項目,請參閱記錄代理程式
  • 如要瞭解稽核與法規遵循需求,請參閱稽核記錄的說明。
  • 如要瞭解如何從應用程式中讀取、寫入及設定記錄,請參閱 Stackdriver Logging API 一文。
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Stackdriver Logging
需要協助嗎?請前往我們的支援網頁