使用 ADOT 來檢測您的 Node.js 函數使用 X-Ray SDK 檢測 Node.js 函數透過 Lambda 主控台來啟用追蹤使用 Lambda 啟用追蹤 API 使用啟用追蹤 AWS CloudFormation 解讀 X-Ray 追蹤在 layer 中存放執行時間相依性 (X-Ray SDK)

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

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

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

AWS Distro for OpenTelemetry (ADOT) – 安全、生產就緒、 AWS支援的 OpenTelemetry (OTel) 分佈SDK。
適用於 Node.js 的 AWS X-Ray SDK – SDK用於產生追蹤資料並將其傳送至 X-Ray 的。

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

重要

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

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

ADOT 提供全受管 Lambda 層，可封裝使用 OTel 收集遙測資料所需的一切SDK。透過取用此層，您可以檢測 Lambda 函數，而無需修改任何函數程式碼。您也可以設定 layer 來執行的自訂初始化OTel。如需詳細資訊，請參閱 ADOT 文件中 Lambda 上 ADOT Collector 的自訂組態。

對於 Node.js 執行期，您可以新增適用於 AWS ADOT Javascript 的受管 Lambda 層，以自動檢測函數。如需如何新增此 layer 的詳細說明，請參閱 ADOT 文件中的適用於 AWS 的 Distro for OpenTelemetry Lambda Support JavaScript。

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

若要記錄 Lambda 函數對應用程式中其他資源所進行之呼叫的詳細資料，您也可以使用適用於 Node.js 的 AWS X-Ray SDK。若要取得 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-RaySDK。例如，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 函數上切換主動追蹤，請按照下列步驟操作：

開啟主動追蹤

開啟 Lambda 主控台中的函數頁面。
選擇一個函數。
選擇組態，然後選擇監控和操作工具。
選擇編輯。
在 X-Ray 下，打開主動追蹤。
選擇 Save (儲存)。

使用 Lambda 啟用追蹤 API

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

下列範例 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
      ...

對於 a 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 Simple Storage Service (Amazon S3) 和 Amazon CloudWatch Logs。

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

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

左側第一個節點代表接收調用請求的 Lambda 服務。第二個節點代表您特定的 Lambda 函數。下列範例顯示了具有這 2 個區段的追蹤。兩者都被命名為 my-function，但其中之一的來源為 AWS::Lambda，而另一個的來源為 AWS::Lambda::Function。如果 AWS::Lambda 區段顯示錯誤，Lambda 服務就會出現問題。如果 AWS::Lambda::Function 區段顯示錯誤，表示您的函數出現了問題。

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

注意

AWS 目前正在對 Lambda 服務實作變更。由於這些變更，您可能會看到系統日誌訊息的結構和內容，與 AWS 帳戶中不同 Lambda 函數發出的追蹤區段之間存在細微差異。

此處顯示的追蹤範例說明了舊式函數區段。下列段落說明了舊式和新式區段之間的差異。

這些變更將在未來幾週內實作，除中國和 GovCloud 區域 AWS 區域以外的所有函數都將轉換為使用新格式的日誌訊息和追蹤區段。

舊式函數區段包含下列子區段：

初始化 - 表示載入函數和執行初始化程式碼所花費的時間。只有函數的每個執行個體所處理的第一個事件會顯示此子區段。
調用 – 表示執行處理常式程式碼所花費的時間。
額外負荷 - 表示 Lambda 執行期為做好準備以處理下一個事件所花費的時間。

新式函數區段不包含 Invocation 子區段。相反地，客戶子區段會直接連接至函數區段。如需舊式和新式函數區段結構的詳細資訊，請參閱了解 X-Ray 追蹤。

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

定價

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

在 layer 中存放執行時間相依性 (X-Ray SDK)

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

以下範例會顯示存放適用於 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:
        - nodejs20.x

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

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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

日誌

使用 TypeScript 建置

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

重要

章節