剖析 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 上執行」一文。

支援的環境：

啟用 Profiler API

使用剖析代理程式之前，請確保基礎 Profiler API 已啟用。您可以查看 API 狀態，或視需要使用 Google Cloud CLI 或 Google Cloud 控制台來啟用 API：

gcloud CLI

  1. 如果您尚未在工作站上安裝 Google Cloud CLI，請參閱 Google Cloud CLI 說明文件。

  2. 執行下列指令：

    gcloud services enable cloudprofiler.googleapis.com

詳情請參閱 gcloud services。

Google Cloud 控制台

  1. Enable the required API.

    Enable the API

  2. 如果畫面顯示「API enabled」，代表 API 已啟用。如果未顯示，請按一下「啟用」按鈕。

將 IAM 角色授予服務帳戶

如果您在 Google Cloud 資源上部署應用程式，且使用的是預設服務帳戶，但尚未修改該服務帳戶的角色授予權限，則可略過本節。

如果您執行下列任何操作，就必須為服務帳戶授予 Cloud Profiler 代理程式 (roles/cloudprofiler.agent) 的 IAM 角色：

  1. 您使用預設服務帳戶，但修改了其角色授予權限。
  2. 您使用的是使用者建立的服務帳戶。
  3. 您使用的是 工作負載身分，請將 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

在所有支援的環境中，您可以先安裝套件 @google-cloud/profiler，然後在應用程式中新增 require 陳述式，再按正常方式部署應用程式，藉此使用 Profiler。

安裝 @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，請執行下列操作：

  1. 安裝最新版本的 Cloud Profiler：

    npm install @google-cloud/profiler

  2. 將應用程式 require 程式碼修改為建立 serviceContext 物件，為 service 指派要剖析的服務名稱。您也可以為 version 指派要剖析的服務版本，但您不一定要指定。如需有關這些設定選項的詳細資訊，請參閱「服務名稱和版本引數」一節。

    require('@google-cloud/profiler').start({
  serviceContext: {
    service: 'your-service',
    version: '1.0.0',
  },
});

GKE

如果是 GKE，請執行下列操作：

  1. 修改 Dockerfile 來安裝 Profiler 套件：

    FROM node:10
...
RUN npm install @google-cloud/profiler

  2. 將應用程式 require 程式碼修改為建立 serviceContext 物件，為 service 指派要剖析的服務名稱。您也可以為 version 指派要剖析的服務版本，但您不一定要指定。如需有關這些設定選項的詳細資訊，請參閱「服務名稱和版本引數」一節。

    require('@google-cloud/profiler').start({
  serviceContext: {
    service: 'your-service',
    version: '1.0.0',
  },
});

App Engine

如果是 App Engine 彈性環境和 App Engine 標準環境，require 程式碼與以下內容類似：

require('@google-cloud/profiler').start();

在 App Engine 環境中，service 和 version 參數都是直接衍生自環境，因此您不用另外指定。因此，您不需要建立 serviceContext 物件。

分析資料

Profiler 收集資料之後，您就可以使用 Profiler 介面查看和分析資料。

前往 Google Cloud 控制台的「Profiler」頁面：

前往「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 執行

只有 Google Kubernetes Engine 設定支援 Linux Alpine 的 Node.js 剖析代理程式。

建構錯誤

如果您執行 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) 時，這會導致程序安全關閉。

後續步驟