剖析 Node.js 應用程式
本頁說明如何修改 Node.js 應用程式以擷取剖析資料,並將那些資料傳送至您的 Google Cloud專案。如需剖析作業的一般資訊,請參閱剖析概念一文。
」。Node.js 適用的剖析類型:
- 堆積
- 實際時間
支援的 Node.js 語言版本:
- Node.js 14 以上版本
- 如要瞭解 Node.js 版本政策,請參閱「發布時間表」。
支援的剖析代理程式版本:
- 支援最新版代理程式。一般來說,系統不支援發布超過一年的版本。建議您使用最新發布的代理程式版本。
支援的作業系統:
- Linux。使用
glibc
或musl
實作標準 C 程式庫的 Linux kernel 支援剖析 Node.js 應用程式。如需 Linux Alpine kernel 專屬的設定資訊,請參閱在 Linux Alpine 上執行一文。
支援的環境:
- Compute Engine
- Google Kubernetes Engine (GKE)
- App Engine 彈性環境
- App Engine 標準環境
- Google Cloud 以外的環境(如要瞭解其他設定需求,請參閱剖析在 Google Cloud以外環境執行的應用程式的相關說明)。
啟用 Profiler API
使用剖析代理程式之前,請確保基礎 Profiler API 已啟用。您可以查看 API 狀態,或視需要使用 Google Cloud CLI 或 Google Cloud 控制台來啟用 API:
gcloud CLI
如果尚未在工作站上安裝 Google Cloud CLI,請參閱 Google Cloud CLI 說明文件。
執行下列指令:
gcloud services enable cloudprofiler.googleapis.com
詳情請參閱 gcloud services
。
Google Cloud 控制台
-
Enable the required API.
如果畫面顯示「API enabled」(API 已啟用),代表 API 已啟用。如果未顯示,請按一下「啟用」按鈕。
將 IAM 角色授予服務帳戶
如果您是在 Google Cloud 資源上部署應用程式,且使用預設服務帳戶,並未修改該服務帳戶的角色授權,則可略過本節。
如果您執行下列任一操作,則需要授予服務帳戶「Cloud Profiler 代理程式 (roles/cloudprofiler.agent
)」IAM 角色:
- 您使用預設服務帳戶,但修改了角色授予。
- 您使用的是使用者建立的服務帳戶。
- 您使用的是 Workload Identity,請將 Cloud Profiler Agent 角色授予 Kubernetes 服務帳戶。
您可以使用Google Cloud 控制台或 Google Cloud CLI,將 IAM 角色授予服務帳戶。舉例來說,您可以使用 gcloud projects add-iam-policy-binding
指令:
gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
--member serviceAccount:MY_SVC_ACCT_ID@GCP_PROJECT_ID.iam.gserviceaccount.com \
--role roles/cloudprofiler.agent
使用先前的指令前,請先替換下列項目:
- GCP_PROJECT_ID:您的專案 ID。
- MY_SVC_ACCT_ID:服務帳戶名稱。
詳情請參閱「管理專案、資料夾和機構的存取權」。
使用 Cloud Profiler
如要透過所有支援的環境使用 Profiler,您可以先安裝套件 @google-cloud/profiler
,在應用程式中新增 require
陳述式,然後按正常方式部署應用程式。
安裝 @google-cloud/profiler
前的注意事項
套件 @google-cloud/profiler
依附於內建模組。我們已為 Node 14 和 16 的 Linux 和 Alpine Linux 提供這個內建模組的預先建構二進位檔。不需要額外的依附元件。
@google-cloud/profiler
會使用 node-pre-gyp
判斷要安裝哪個預先建構的二進位檔。
在沒有預先建構二進位檔的其他環境中使用 @google-cloud/profiler
時,模組 node-gyp
會用於建構二進位檔。如要瞭解使用 node-gyp
建構二進位檔時所需的依附元件,請參閱 node-gyp
的安裝說明文件。
安裝
如要安裝最新版本的 Cloud Profiler,請執行以下指令:
npm install @google-cloud/profiler
如果您也使用 Trace 代理程式,修改應用程式時,請先匯入 Trace 代理程式套件 (@google-cloud/trace-agent
),再匯入 Profiler 套件。
Compute Engine
如果是 Compute Engine,請執行下列操作:
安裝最新版 Cloud Profiler:
npm install @google-cloud/profiler
修改應用程式的
require
程式碼,建立serviceContext
物件,並將要剖析的服務名稱指派給service
。此外,您也可以為version
指派要剖析的服務的版本,但您不一定要指定。如需有關這些設定選項的詳細資訊,請參閱服務名稱和版本引數。
GKE
如果是 GKE,請執行下列操作:
修改 Dockerfile 來安裝 Profiler 套件:
FROM node:10 ... RUN npm install @google-cloud/profiler
修改應用程式的
require
程式碼,建立serviceContext
物件,並將要剖析的服務名稱指派給service
。此外,您也可以為version
指派要剖析的服務的版本,但您不一定要指定。如需有關這些設定選項的詳細資訊,請參閱服務名稱和版本引數。
App Engine
如果是 App Engine 彈性環境和 App Engine 標準環境,require
程式碼與以下內容類似:
在 App Engine 環境中,service
和 version
參數都是直接衍生自環境,因此您不用另外指定。因此,您不需要建立 serviceContext
物件。
分析資料
Profiler 收集資料之後,您就可以使用 Profiler 介面來查看和分析資料。
前往 Google Cloud 控制台的「Profiler」頁面:
您也可以透過搜尋列找到這個頁面。
服務名稱和版本引數
載入 Profiler 代理程式時,您可指定 service-name 引數及 service-version 引數 (選用) 來加以設定。
「service name」(服務名稱) 可讓 Profiler 收集有關這項服務的所有備用資源剖析資料。分析器服務會針對每個服務名稱的各個版本及區域組合,確保平均每分鐘一個剖析作業的收集頻率。
舉例來說,如果您有一個服務,共有兩個版本在三個區域的備用資源執行,則分析器會為這個服務建立平均每分鐘 6 個剖析作業。
如果您為備用資源使用不同的服務名稱,系統剖析服務的頻率就會比平常更高,相對地負擔也會更大。
選取服務名稱時:
選擇的名稱要能清楚代表應用程式架構中的服務。如果您只執行單一服務或應用程式,服務名稱的選擇就不那麼重要;但如果應用程式是以一組微服務的形式執行,建議就應選擇適當的服務名稱。
請勿在 service-name 字串中使用任何 process-specific 值 (例如 ID)。
service-name 字串必須符合這個規則運算式:
^[a-z0-9]([-a-z0-9_.]{0,253}[a-z0-9])?$
使用靜態字串 (如 imageproc-service
) 做為服務名稱就是不錯的做法。
「service version」(服務版本) 則為選填項目。如果您指定服務版本,Profiler 可從多個執行個體匯總剖析資訊並正確顯示;這項引數可用來標記服務部署時的不同版本。Profiler UI 可讓您按照服務版本篩選資料,這樣一來,您就能比較新舊版程式碼的運作效能。
service-version 引數的值是任意形式的字串,不過這個引數的值看起來通常和版本號碼類似,例如 1.0.0
或 2.1.2
。
代理程式記錄
剖析代理程式可報告記錄資訊。如要啟用記錄功能,請在啟動代理程式時設定 logLevel
選項。支援的 logLevel
值如下:
0
:停用所有代理程式記錄。1
:啟用錯誤記錄。2
:啟用警告記錄 (預設)。3
:啟用資訊記錄。4
:啟用偵錯記錄
在提供服務背景內容的同一個物件中設定 logLevel
值:
require('@google-cloud/profiler').start({
serviceContext: { ... }
logLevel: 3
});
使用 Linux Alpine 執行
Linux Alpine 的 Node.js 剖析代理程式僅支援 Google Kubernetes Engine 設定。
建構錯誤
如果您執行 npm install
,但建構作業失敗並顯示下列錯誤,表示 Dockerfile 缺少一些建構依附元件:
ERR! stack Error: not found: make
如要解決這個問題,請將下列陳述式新增至 Dockerfile 的建構階段:
RUN apk add python3 g++ make
驗證錯誤
如果您使用 Docker 映像檔,且這些映像檔透過 Linux Alpine (例如 golang:alpine
或只有 alpine
) 執行,可能會看到下列驗證錯誤:
connection error: desc = "transport: authentication handshake failed: x509: failed to load system roots and no roots provided"
請注意,要啟用代理程式記錄功能才能看到錯誤。
以上錯誤指出,透過 Linux Alpine 執行的 Docker 映像檔根據預設並未安裝 SSL 根憑證。如果要讓剖析代理程式與 Profiler API 相互通訊,就必須具有這些憑證。如要解決這項錯誤,請在 Dockerfile 中新增下列 apk
指令:
FROM alpine
...
RUN apk add --no-cache ca-certificates
接著您必須重新建構和重新部署應用程式。
已知問題
Node.js 的剖析代理程式會干擾程式的正常離開程序;程式中所有工作都完成後,終止程式可能需要花費長達一小時的時間。發出 SIGINT 時 (例如使用 Ctrl-C
),程序會安全終止。