在中檢測 Node.js 程式碼 AWS Lambda

Lambda 與 AWS X-Ray 整合，可協助您追蹤、偵錯和最佳化 Lambda 應用程式。您可以使用 X-Ray 來追蹤請求，因為它會周遊您應用程式中的資源，其中可能包含 Lambda 函數和其他 AWS 服務。

若要將追蹤資料傳送至 X-Ray，您可以使用以下兩個 SDK 庫之一：

• AWS 適用於 OpenTelemetry (ADOT) 的發行版 — 安全、可生產就緒且 AWS支援的 (OTel) SDK 發行 OpenTelemetry 版。

• 適用於 Node.js 的 AWS X-Ray SDK – 用於生成追蹤資料並將其傳送至 X-Ray 的 SDK。

每個 SDK 均提供將遙測資料傳送至 X-Ray 服務的方法。然後，您可以使用 X-Ray 來檢視、篩選應用程式的效能指標並獲得洞察，從而識別問題和進行最佳化的機會。

重要

用於 AWS Lambda SDK 的 X-Ray 和 Powertools 是由提供的緊密集成的儀表解決方案的一部分。 AWS ADOT Lambda Layers 是用於追蹤檢測之業界通用標準的一部分，這類檢測一般會收集更多資料，但可能不適用於所有使用案例。您可以使用任一解決方案在 X-Ray 中實作 end-to-end 追蹤。若要深入了解如何在兩者之間做選擇，請參閱在 AWS Distro for OpenTelemetry 和 X-Ray SDK 之間進行選擇。

使用 ADOT 來檢測您的 Node.js 函數

ADOT 提供全受管 Lambda 層，包含使用 OTel SDK 收集遙測資料所需的一切內容。透過取用此層，您可以檢測 Lambda 函數，而無需修改任何函數程式碼。您還可以將層設定為對 OTel 進行自訂初始化。如需詳細資訊，請參閱 ADOT 文件中的針對 Lambda 上的 ADOT 收集器進行自訂組態設定。

針對 Python 執行階段，您可以新增適用於 ADOT Javascript 的AWS 受管 Lambda 層來自動檢測您的函數。有關如何添加此層的詳細說明，請參閱 AWS ADOT 文檔 JavaScript中的 OpenTelemetry Lambda Support 發行版。

使用 X-Ray SDK 來檢測 Node.js 函數

若要記錄 Lambda 函數對應用程式中其他資源所進行之呼叫的詳細資料，您也可以使用 適用於 Node.js 的 AWS X-Ray SDK。若要取得開發套件，請將 aws-xray-sdk-core 套件新增至應用程式的相依性。

範例 blank-nodejs/package.json

{
  "name": "blank-nodejs",
  "version": "1.0.0",
  "private": true,
  "devDependencies": {
    "jest": "29.7.0"
  },
  "dependencies": {
    "@aws-sdk/client-lambda": "3.345.0",
    "aws-xray-sdk-core": "3.5.3"
  },
  "scripts": {
    "test": "jest"
  }
}

要在 AWS SDK for JavaScript v3 中檢測 AWS SDK 客戶端，請使用該captureAWSv3Client方法包裝客戶端實例。

範例 blank-nodejs/function/index.js — 追蹤 AWS SDK 用戶端

const AWSXRay = require('aws-xray-sdk-core');
const { LambdaClient, GetAccountSettingsCommand } = require('@aws-sdk/client-lambda');

// Create client outside of handler to reuse
const lambda = AWSXRay.captureAWSv3Client(new LambdaClient());

// Handler
exports.handler = async function(event, context) {
    event.Records.forEach(record => {
  ...

Lambda 執行階段會設定一些環境變數，以配置 X-Ray SDK。例如，Lambda 會將 AWS_XRAY_CONTEXT_MISSING 設定為 LOG_ERROR，以避免從 X-Ray SDK 中擲回執行階段錯誤。若要設置自訂內容遺失策略，請覆寫函式組態中的環境變數以使其不要有值，然後您可以透過程式設計方式設置內容遺失策略。

範例 初始化程式碼範例

const AWSXRay = require('aws-xray-sdk-core');

// Configure the context missing strategy to do nothing
AWSXRay.setContextMissingStrategy(() => {});

如需詳細資訊，請參閱 使用 Lambda 環境變數來設定程式碼中的值。

新增正確的依賴項並進行必要的程式碼變更後，請透過 Lambda 主控台或 API 在函數的組態中啟用追蹤。

透過 Lambda 主控台來啟用追蹤

若要使用控制台在 Lambda 函數上切換主動追蹤，請按照下列步驟操作：

開啟主動追蹤

1. 開啟 Lambda 主控台中的 函數頁面。

2. 選擇一個函數。

3. 選擇 組態 ，然後選擇 監控和操作工具 。

4. 選擇 編輯 。

5. 在 X-Ray 下，打開 主動追蹤 。

6. 選擇 儲存 。

透過 Lambda API 啟用追蹤

使用 AWS CLI 或 AWS SDK 在 Lambda 函數上設定追蹤，並使用下列 API 作業：

• UpdateFunction配置

• GetFunction配置

• CreateFunction

下列範例 AWS CLI 命令可在名為 my- function 的函式上啟用主動追蹤。

aws lambda update-function-configuration \
--function-name my-function \
--tracing-config Mode=Active

追蹤模式是您發布函數版本時版本特定組態的一部分。您無法變更已發佈版本上的追蹤模式。

使用啟動追蹤 AWS CloudFormation

若要啟動 AWS CloudFormation 範本中的AWS::Lambda::Function資源追蹤，請使用TracingConfig屬性。

範例 function-inline.yml - 追蹤組態

Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

對於 AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function 資源，請使用Tracing屬性。

範例 template.yml - 追蹤組態

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

解讀 X-Ray 追蹤

您的函數需要將追蹤資料上傳至 X-Ray 的許可。當您在 Lambda 主控台中啟用追蹤時，Lambda 會將必要的許可新增至函數的執行角色。否則，請將AWSXRayDaemonWriteAccess原則新增至執行角色。

設定主動追蹤之後，您可以透過應用程式來觀察特定請求。X-Ray 服務圖顯示了有關應用程式及其所有元件的資訊。下圖演示了具有兩個功能的應用程序。主要函式會處理事件，有時會傳回錯誤。頂部的第二個函數處理出現在第一個日誌組中的錯誤，並使用 AWS SDK 調用 X-Ray，Amazon 簡單存儲服務（Amazon S3）和亞馬遜 CloudWatch 日誌。

X-Ray 無法追蹤應用程式的所有請求。X-Ray 會套用取樣演算法以確保追蹤的效率，同時仍提供所有請求的代表範本。取樣率為每秒 1 次請求和 5% 的額外請求。

注意

您無法針對函數設定 X-Ray 取樣率。

在 X-Ray 中，追蹤會記錄一或多個服務所處理之要求的相關資訊。Lambda 會記錄每個追蹤 2 個區段，在服務圖表上建立兩個節點。下列影像會強調顯示這兩個節點：

左側第一個節點代表接收調用請求的 Lambda 服務。第二個節點代表您特定的 Lambda 函數。下列範例顯示了具有這 2 個區段的追蹤。兩者都被命名為我的函數，但一個具有的起源AWS::Lambda，另一個具有的AWS::Lambda::Function起源。如果AWS::Lambda區段顯示錯誤，表示 Lambda 服務發生問題。如果AWS::Lambda::Function區段顯示錯誤，表示您的函數發生問題。

此範例會展開區AWS::Lambda::Function段，以顯示其三個子區段：

• 初始化 - 表示載入函數和執行初始化程式碼所花費的時間。只有函數的每個執行個體所處理的第一個事件會顯示此子區段。

• 調用 – 表示執行處理常式程式碼所花費的時間。

• 額外負荷 - 表示 Lambda 執行期為做好準備以處理下一個事件所花費的時間。

您也可以檢測 HTTP 用戶端、記錄 SQL 查詢，以及建立具有註釋和中繼資料的自訂子區段。如需詳細資訊，請參閱《AWS X-Ray 開發人員指南》中的 適用於 Node.js 的 AWS X-Ray SDK 許可。

定價

作為免費方案的一部分，您可以每月免費使用 X-Ray 追蹤，最多達到一定限制。 AWS 達到閾值後，X-Ray 會收取追蹤儲存及擷取的費用。如需詳細資訊，請參閱 AWS X-Ray 定價。

將執行時間相依項存放存在層中 (X-Ray SDK)

如果您使用 X-Ray SDK 來檢測 AWS SDK 用戶端您的函數程式碼，您的部署套件可能會變得相當大。為了避免每次更新函數程式碼時上傳執行時間相依性，請將 X-Ray SDK 封裝在一個 Lambda 層中。

以下範例會顯示存放 適用於 Node.js 的 AWS X-Ray SDK的 AWS::Serverless::LayerVersion 資源。

範例 template.yml - 相依性層

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: function/.
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - nodejs16.x

透過此組態，您只有在變更執行時間相依性時才會更新程式庫層。由於函數部署套件僅含有您的程式碼，因此有助於減少上傳時間。

為相依性建立圖層需要建置變更，才能在部署之前產生圖層封存。如需工作範例，請參閱 blank-nodejs 範例應用程式。