使用 Google Stackdriver 偵錯、追蹤、記錄和記錄點

本教學課程將為您介紹 Google Stackdriver，您可以透過 Google Cloud Platform 應用程式執行以下操作：

• 針對在 App Engine、Compute Engine 和 Container Engine 上執行的應用程式，執行偵錯快照。
• 查看應用程式紀錄。
• 設定指標並監控指標，並取得快訊。
• 追蹤 API 呼叫，並查看程式碼回應時間與潛在瓶頸細目。
• 在紀錄應用程式中加入記錄點，完全不必部署應用程式，這項功能是真正獨到 (且非常有用) 的功能。

在本教學課程中，我們將從頭開始建立以下項目：

1. 建立 Google Cloud Platform 專案 (僅限 App Engine)
2. 設定 Google Cloud Platform 專案原始碼存放區
3. 使用來自 GitHub 的標準標準訪客 Python 應用程式原始碼
4. 部署程式碼
5. 瞭解我們如何取得執行應用程式的偵錯快照
6. 查看 Logging 和應用程式呼叫追蹤記錄
7. 將記錄點新增至目前執行中的應用程式。這項功能最初在以下網誌文章中介紹了：將應用程式應用程式記錄新增至沒有重新啟動的應用程式

開始教學課程！

這些內容最初是由 Romin Irani 所建立，並張貼到這裡。

自行調整環境設定

如果您還沒有 Google 帳戶 (Gmail 或 Google Apps)，請先建立帳戶。登入 Google Cloud Platform 主控台 (console.cloud.google.com)，然後建立新專案：

提醒您，專案編號是所有 Google Cloud 專案的不重複名稱 (使用上述名稱後就無法使用，敬請見諒！)此程式碼研究室稍後將稱為 PROJECT_ID。

接著，您必須在 Cloud Console 中啟用計費功能，才能使用 Google Cloud 資源。

完成這個程式碼研究室的成本應該不會超過新臺幣 $300 元，但如果您決定繼續使用更多資源，或是讓資源繼續運作 (請參閱本文件結尾的「清除設定」一節)，就有可能需要更多成本。

新加入 Google Cloud Platform 的使用者可免費試用 $300 美元。

Google Cloud Shell

在本程式碼研究室中，我們將使用在 Google Cloud 中執行的指令列環境 Google Cloud Shell。

這款以 Debian 為基礎的虛擬機器會載入您需要的所有開發工具。這項服務提供永久性的 5GB 主目錄，可在 Google Cloud 中運作，大幅提升網路效能和驗證效能。也就是說，這個程式碼研究室只需使用瀏覽器 (是，您可以在 Chromebook 上使用)。

如要啟用 Google Cloud Shell，只要在開發人員控制台中，按一下右上角的按鈕 (只需幾分鐘即可佈建並連線至環境)：

然後接受服務條款並按一下 [Start Cloud Shell] 連結：

連線至 Cloud Shell 之後，您應該會看到您已經通過驗證，且專案已設為 PROJECT_ID。

gcloud auth list

指令輸出

Credentialed accounts:
 - <myaccount>@<mydomain>.com (active)

注意：gcloud 是 Google Cloud Platform 功能強大的指令列工具。如需完整說明文件，請前往 https://cloud.google.com/sdk/gcloud。Cloud Shell 已預先安裝於 CloudShell 中，且完全支援分頁自動完成功能。

gcloud config list project

指令輸出

[core]
project = <PROJECT_ID>

如果因為某些原因而無法設定專案，只要發出下列指令即可：

gcloud config set project <PROJECT_ID>

正在尋找您的 PROJECT_ID 嗎？您可以查看在設定步驟中使用的 ID，或是在控制台資訊主頁查詢 ID：

重要事項：最後，請設定預設區域和專案設定：

gcloud config set compute/zone us-central1-f

您可以選擇多種不同的區域。詳情請參閱地區和區域說明文件。

注意：在您的電腦上執行 gcloud 時，組態設定會維持所有工作階段的保留狀態。但在 Cloud Shell 中，您必須為每次新的工作階段或重新連線都設定一次。

查看已啟用的 StackDriver API

讓我們來看看您的專案已啟用的 API。使用搜尋列找出 API 資訊主頁，如下所示。

觀察您的專案已啟用的特定 API：

每個 Google Cloud Platform 專案都提供私人 Git 託管功能，但我們必須先建立預設存放區才能使用。使用主控台搜尋框瀏覽至原始碼存放區：

按一下 [建立存放區] 來建立名稱為「default」的新建程式碼存放區：

我們現在將使用 Cloud Shell 來將這個目錄複製到 Google Cloud Shell 執行個體中。如要這麼做，請先在 Google Cloud Shell 執行個體中建立一個目錄，然後前往下方目錄 (輸出範例)：

mkdir stackdriver-demo

cd stackdriver-demo/

現在，我們可以透過 gcloud 指令來複製預設存放區，如下所示：

gcloud source repos clone default

這是主控台結果：

Cloning into '/home/gcp123_student/default'...
warning: You appear to have cloned an empty repository.
Project [qwiklabs-gcp-1234abc1234] repository [default] was cloned to [/home/gcp123_student/default].

漂亮！讓我們先花點時間深入瞭解已經設定的 Git 遙控器。這並不一定是一件事情，而是讓您更瞭解幕後的運作情形。

前往預設目錄並啟動 git remote -v 指令，如下所示

cd default

git remote -v

這是主控台輸出結果，如下所示：

origin https://source.developers.google.com/p/qwiklabs-gcp-1234abc1234/r/default (fetch)
origin https://source.developers.google.com/p/qwiklabs-gcp-1234abc1234/r/default (push)

您可以看到，這可正確指向與 GCP 專案相關聯的 Git 存放區。

從 GitHub 提取留言板應用程式

我們預計將使用名為 Guestbook 的標準 App Engine 應用程式，該應用程式可在官方的 Google Cloud Platform GitHub 存放區中找到。這份應用程式也包含在這份官方說明文件中，可協助您快速上手。Github 專案可於 https://github.com/GoogleCloudPlatform/appengine-留言板-python 取得。

現在我們要把此程式碼提取到 Cloud Shell 執行個體中。相關指令及其輸出內容如下所示：

git pull https://github.com/GoogleCloudPlatform/appengine-guestbook-python

這是主控台結果：

remote: Counting objects: 485, done.
remote: Total 485 (delta 0), reused 0 (delta 0), pack-reused 485
Receiving objects: 100% (485/485), 436.42 KiB | 163.00 KiB/s, done.
Resolving deltas: 100% (195/195), done.
From https://github.com/GoogleCloudPlatform/appengine-guestbook-python
* branch HEAD -> FETCH_HEAD

現在所有程式碼都已在本機的 Google Cloud Shell 執行個體中顯示。您可以查看已從 GitHub 專案中提取的各種檔案。

使用 Cloud Shell 將目前的程式碼推送至 Project Git 存放區

現在，請將此程式碼推送至 GCP Project Git 存放區，以便針對程式碼設定中斷點、記錄點和其他項目。請注意，這並非強制性步驟，因為您可以直接與 GitHub 、本機電腦及其他整合原始碼的方式整合。

但為了方便起見，我們會將此程式碼推送至 GCP Project Git 存放區。透過標準 git push 指令完成，如下所示：

git push origin master

這是主控台結果：

Counting objects: 485, done.
Compressing objects: 100% (280/280), done.
Writing objects: 100% (485/485), 436.42 KiB | 0 bytes/s, done.
Total 485 (delta 195), reused 485 (delta 195)
remote: Storing objects: 100% (485/485), done.
remote: Processing commits: 100% (152/152), done.
To https://source.developers.google.com/p/qwiklabs-gcp-1234abc1234/r/default
* [new branch] master -> master

現在，請回到 GCP Cloud Console，尤其是「開發」部分。按一下 [原始碼] 後，即可檢視預設存放區的所有專案檔案。輸出範例顯示如下：

現在我們已完成相關設定，可以部署 Guestbook App Engine 應用程式。如要部署應用程式，請確認您位於 Google Cloud Shell 和預設目錄中。使用 gcloud app deploy 指令，如下所示：

gcloud app deploy --version 1

當系統要求您選擇地區時，請選取 [1] us-east1。

這是主控台結果：

You are about to deploy the following services:
— qwiklabs-gcp-1234abc1234/default/1 (from [/home/gcp123-student/default/app.yaml])
Deployed URL: [https://qwiklabs-gcp-1234abc1234.appspot.com]
Do you want to continue (Y/n)? Y
Beginning deployment of service [default]...
File upload done.
Updating service [default]...done.
Deployed service [default] to https://qwiklabs-gcp-1234abc1234.appspot.com]

請注意，我們已為 app deploy 指令提供版本參數。我們得到的值為 "1"。

訪客應用程式是透過 Google Cloud Datastore 建立，因此必須更新 Datastore 索引。索引是在 index.yaml 檔案中指定，我們只使用 gcloud datastore create-indexes 指令，如下所示：

gcloud datastore create-indexes index.yaml

這是主控台結果：

You are about to update the following configurations:
— qwiklabs-gcp-1234abc1234/index From: [/home/gcp123_student/default/index.yaml]
Do you want to continue (Y/n)? Y

資料儲存庫索引可能需要一點時間才能完成更新。如要查看狀態，請搜尋「Datastore 索引」，然後按一下 [索引]。建立索引時，您會看到 [索引] 值為「狀態」，如下所示：

您可以前往 [Compute] → [App Engine]，然後點擊 [版本]，確認是否已部署第 1 版的應用程式：

現在一切就緒，您可以前往 https://<PROJECT_ID>.appspot.com 查看專案。再次提醒您，資料儲存庫索引可能需要幾分鐘的時間才會完成，因此如果應用程式發生錯誤 (例如：內部伺服器錯誤)，請過幾分鐘後再試一次。

現在，讓我們登入並建立幾個留言板項目，以使用應用程式，如下所示：

漂亮！現在，我們已經深入探討 Stackdriver 的功能了。

現在就讓我們來瞭解如何對執行中的應用程式拍攝快照。如果您想對特定程式碼進行偵錯、檢查變數以及執行其他操作，「快照」就可以派上用場。如此一來，您的應用程式服務仍在執行時，就會發生這種情形。這項功能在回報應用程式問題，而且您想要嘗試進行偵錯，並查看應用程式發生的問題、檢查許多變數、有條件地拍攝快照等。

現在，讓我們為「留言板」應用程式進行這些操作。如果有人要求取得首頁，尤其是希望 Google 擷取該資料儲存庫中的問候語清單，我們將要求取得快照。

這個檔案的程式碼位於 guestbook.py 檔案中。具體來說，如果從資料儲存庫擷取問候語清單，我們希望能在執行階段檢查程式碼。這一行會在第 72 行完成。因此，我們可以在第 74 行放置一個潛力點，以便我們知道 #72 已執行。

方法是在 App Engine 版本檢視畫面中按一下 [偵錯]，或前往 Stackdriver → 偵錯 。螢幕上會顯示下方的畫面。請在左側選取檔案 (guestbook.py)，然後按一下所顯示的行號。

這會以方框特別標出上方紅色方塊內的訊息，表示正在等候快照觸發。現在，我們只要前往網頁

https://<PROJECT_ID>.appspot.com。

完成上述步驟後，快照就會啟用，接著您會看到「變數」和「呼叫堆疊」部分填入資料，如下所示。查看變數的顯示方式，您可以將其展開並檢查其值。這非常實用。

例如，如果您展開問候語變數，該變數的紀錄就會對應至您先前建立的留言板項目數目。

每次需要時都可輕鬆拍攝快照，您只要按一下相機圖示，系統就能再次顯示快照，如下所示：

您可以按照下方的「運算式」欄位追蹤特定變數。舉例來說，我們知道我們有不同的問候語，在查看快照時，我們想要查看其價值。我們可以插入問候語變數，如以下螢幕擷取畫面所示。快照發揮作用時，系統會將快照填入顯示的值。

如果您想讓快照只在特定條件啟用，可以使用 [Condition] 欄位，如下所示。在這裡，我們只會在快照問候數大於 1 時才會建立快照。如有需要，您可以嘗試這個做法。

注意：如需完整的 Stackdriver Debugger 說明文件，請造訪以下網址：https://cloud.google.com/debugger/docs/

請務必確認您的網頁效能符合您設定的條件。Stackdriver Trace 是一項關鍵工具，可協助您瞭解應用程式的延遲時間。

在預設情況下，所有 App Engine 應用程式均會啟用這項功能，並提供所有端點的效能詳細資料，以及執行各種呼叫的明細。

我們的案例已經進入首頁 (「/」) 並瀏覽 / 新增留言板項目。這就可讓 Trace 更及時得知延遲時間。只要瀏覽至 Stackdriver Trace 總覽頁面，下方就會顯示螢幕截圖。查看近期追蹤記錄及其延遲時間。

如果我們點選任一追蹤記錄 (也就是點擊 URI 連結)，便會顯示詳細的追蹤記錄，如下所示：

請注意，我們該如何細分延遲，以及哪些通話花費的時間最多。從上圖可以看出，資料儲存庫查詢需要一些時間。其中一個選項是快取資料以減少該瓶頸。再次提醒您，這要視您的應用程式而定，在進行追蹤追蹤記錄時，您可能需要進行一些重構，這對於非常有幫助。

注意：如需完整的 Stackdriver Trace 說明文件，請參閱：https://cloud.google.com/trace/docs/

您隨時可以前往 Stackdriver Logging 查看應用程式紀錄 (如下所示)。您可選用多種篩選器，從各種 GCP 服務著手 → 記錄類型 → 記錄層級 → 日期等等。

下方的螢幕截圖顯示 App Engine 應用程式的預設紀錄和預設的版本 1。

注意：如需完整的 Stackdriver Logging 說明文件，請參閱：https://cloud.google.com/logging/docs/

最後，我們要介紹一項功能，希望能夠讓您滿懷期待。一般而言，開發人員會盡可能將紀錄陳述式放入程式碼中，並部署程式碼，這樣我們就知道所有需要知道的資訊。

但這只是因為我們沒有充分能力在偵錯作業，也瞭解到這裡應該可以再多加入幾個記錄陳述式。然後，一般的工作流程是修改程式碼，輸入額外的記錄陳述式，重新部署並監控。

這沒關係，但如果您可以在紀錄應用程式中加入這些紀錄陳述式 (立即將記錄命名為 logpoints)，就可以了。這表示我們不需要執行停止應用程式、變更程式碼和重新部署的程序。因此，我們可以透過記錄點支援，管理應用程式外的記錄點清單。

在 Cloud Shell 中，我們來檢查目前設定的記錄點清單 (看起來應該是 0)。這可透過 gcloud 指令完成，如下所示：

gcloud debug logpoints list

這是主控台結果：

Debug target not specified. Using default target: default-1
Listed 0 items.

現在，我們要在執行的應用程式中加入記錄點。如要新增記錄點，我們必須執行以下動作：

• 找出要新增記錄點的原始碼檔案和行號。
• 找出記錄訊息。此記錄訊息可以硬式編碼，甚至是運算式。

在我們的案例中，我們會透過記錄點 create 指令，將記錄點新增至第 74 行的 safari.py 檔案，如下所示：

gcloud debug logpoints create guestbook.py:74 "Fetched greetings from Datastore. Count of greetings : {len(greetings)}"

這是主控台結果：

Debug target not specified. Using default target: default-1
— id: 53538243519d4-f9a0-bdbce
location: guestbook.py:74
logLevel: INFO
logMessageFormat: Fetched greetings from Datastore. Count of greetings : {len(greetings)}
condition: None
status: ACTIVE

我們已提供上述的 filename:linenumber 訊息和記錄訊息。請注意，我們的記錄訊息也包含一個運算式，可列印我們從資料儲存庫擷取的問候數。

指令會回頭顯示已新增記錄點的訊息。Cloud Shell 的螢幕截圖如下：

現在，如果您啟動記錄點清單指令，將會顯示以下輸出：

gcloud debug logpoints list

這是主控台結果：

Debug target not specified. Using default target: default-1
STATUS LOCATION CONDITION LOG_LEVEL LOG_MESSAGE_FORMAT ID
ACTIVE
guestbook.py:74 INFO Fetched greetings from Datastore. Count of greetings : {len(greetings)} 53538243519d4-f9a0-bdbce

如要瞭解這個情況，我們可以再次前往首頁 (https://<PROJECT_ID>.appspot.com)。這會叫用程式碼，並產生記錄點。請注意，根據預設，應用程式紀錄會記錄這項動作。因此，您只需要再前往 Stackdriver Logging 一次，如下所示：

按一下該要求和 Valea！詳細資料中會顯示記錄點已觸發，並顯示記錄訊息。

希望您對這個教學課程感到滿意。它只具備 Stackdriver 平台應用到資料表的幾項功能。還有許多值得探索的地方。歡迎造訪 https://rominirani.com/ 閱讀 Romin Irani's 網誌 (本程式碼研究室的原始作者)，瞭解更多 Google Cloud Platform 教學課程。

您也可以參閱「使用 Stackdriver 監控與記錄」的其他程式碼研究室，進一步瞭解應用程式的健康狀態。

如果您有任何意見，或想回報這個程式碼研究室的問題，請使用這個網頁下方的 [請尋找錯誤] 連結。