Node.js 関数の計測での ADOT の使用 X-Ray SDK を使用した Node.js 関数の計測 Lambda コンソールを使用してトレースを有効化する Lambda API でのトレースのアクティブ化 AWS CloudFormation によるトレースのアクティブ化 X-Ray トレースの解釈ランタイムの依存関係をレイヤー (X-Ray SDK) に保存する

AWS Lambda での Node.js コードの作成

Lambda アプリケーションのトレース、デバッグ、最適化を行うために、Lambda は AWS X-Ray と統合されています。X-Ray を使用すると、Lambda 関数や他の AWS のサービスが含まれるアプリケーション内で、リソースを横断するリクエストをトレースできます。

トレースされたデータを X-Ray に送信するには、以下の 2 つの SDK ライブラリのいずれかを使用します。

AWS Distro for OpenTelemetry (ADOT) – 安全で、本番環境に対応し、AWS でサポートされている OpenTelemetry (OTel) SDK のディストリビューションです。
AWS X-Ray SDK for Node.js - トレースデータを生成して X-Ray に送信するための SDK です。

各 SDK は、テレメトリデータを X-Ray サービスに送信する方法を提供します。続いて、X-Ray を使用してアプリケーションのパフォーマンスメトリクスの表示やフィルタリングを行い、インサイトを取得することで、問題点や最適化の機会を特定できます。

重要

X-Ray および Powertools for AWS Lambda SDK は、AWS が提供する、密接に統合された計測ソリューションの一部です。ADOT Lambda レイヤーは、一般的により多くのデータを収集するトレーシング計測の業界標準の一部ですが、すべてのユースケースに適しているわけではありません。これらのソリューションのいずれかを使用して、X-Ray でエンドツーエンドのトレーシングを実装することができます。選択方法の詳細については、「Choosing between the AWS Distro for Open Telemetry and X-Ray SDKs」( Distro for Open Telemetry または X-Ray SDK の選択) を参照してください。

Node.js 関数の計測での ADOT の使用

ADOT はフルマネージド型の Lambda レイヤーを提供します。これにより、OTel SDK を使用してテレメトリデータを収集するために必要なすべてがパッケージ化されます。このレイヤーを使用すると、関数コードを変更する必要はなしで、Lambda 関数を計測できます。また、このレイヤーは、OTel でのカスタムな初期化を実行するように構成することもできます。詳細については、ADOT のドキュメントにある「Lambda 上での ADOT Collector のカスタム設定」を参照してください。

Node.js ランタイムの場合は、ADOT Javascript 向け AWS マネージド Lambda レイヤー を追加して、関数を自動的に計測できます。このレイヤーを追加する方法の詳しい手順については、「ADOT ドキュメント」で「JavaScript に対する AWS Distro for OpenTelemetry Lambda のサポート」を参照してください。

X-Ray SDK を使用した Node.js 関数の計測

Lambda 関数がアプリケーション内の他のリソースに対して行う呼び出しの詳細を記録するために、AWS X-Ray SDK for Node.js を使用することもできます。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 クライアントを AWS SDK for JavaScript v3 で計測するには、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 は、X-Ray SDK からランタイムエラーがスローされないように、LOG_ERROR に AWS_XRAY_CONTEXT_MISSING をセットします。カスタムのコンテキストミッシング戦略を設定するには、関数設定の環境変数をオーバーライドして値を持たせないようにします。その後、コンテキストミッシング戦略をプログラムで設定できます。

例初期化コードの例


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] で、[アクティブトレース] をオンに切り替えます。
[保存] をクリックします。

Lambda API でのトレースのアクティブ化

AWS CLI または AWS SDK で Lambda 関数のトレースを設定するには、次の 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
      ...

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 サービスグラフ] には、アプリケーションとそのすべてのコンポーネントに関する情報が表示されます。次の例は、2 つの関数を持つアプリケーションを示しています。プライマリ関数はイベントを処理し、エラーを返す場合があります。上位 2 番目の関数は、最初のロググループに表示されるエラーを処理し、AWS SDKを使用してX-Ray、Amazon Simple Storage Service (Amazon S3)、および Amazon CloudWatch Logs を呼び出します。

X-Ray の 2 つの個別のアプリケーションおよびそれぞれに関係するサービスマップを示した図

X-Ray は、アプリケーションへのすべてのリクエストをトレースするわけではありません。X-Ray は、サンプリングアルゴリズムを適用することで効率的なトレースを行うと同時に、すべてのリクエストについての代表的なサンプルを示します。サンプルレートは 1 秒あたり 1 回のリクエストで、追加リクエストの 5％です。関数の X-Ray サンプルレートを設定することはできません。

X-Ray では、トレースは 1 つ以上のサービスによって処理されるリクエストに関する情報を記録します。Lambda はトレースごとに 2 つのセグメントを記録します。これにより、サービスグラフに 2 つのノードが作成されます。次の図は、これら 2 つのノードを強調表示しています。

左に示された 1 つめのノードは、呼び出しリクエストを受信する Lambda サービスを表しています。2 つめのノードは、特定の Lambda 関数を表しています。次の例は、これら 2 つのセグメントを使用したトレースを示しています。いずれも my-function と名付けられていますが、1 つは AWS::Lambda の起点があり、もう 1 つは AWS::Lambda::Function の起点があります。AWS::Lambda セグメントにエラーが表示される場合は、Lambda サービスに問題があります。AWS::Lambda::Function セグメントにエラーが表示される場合、関数に問題があります。

特定の Lambda 呼び出しの各サブセグメント間に生じるレイテンシーを示した X-Ray トレースです。

この例では、AWS::Lambda::Function セグメントを展開して、それの 3 つのサブセグメントが表示されています。

注記

AWS は現在、Lambda サービスに変更を実装しています。これらの変更により、AWS アカウントのさまざまな Lambda 関数によって出力されるシステムログメッセージとトレースセグメントの構造と内容にわずかな違いが生じる場合があります。

ここで示すトレースの例は、古いスタイルの関数セグメントを示しています。古いスタイルのセグメントと新しいスタイルのセグメントの違いについては、次の段落で説明します。

これらの変更は今後数週間に実装され、中国および GovCloud リージョンを除くすべての AWS リージョンのすべての関数は、新しい形式のログメッセージとトレースセグメントを使用するように移行されます。

古いスタイルの関数セグメントには、次のサブセグメントが含まれます。

初期化 －関数のロードと初期化コードの実行に要した時間を表します。このサブセグメントは、関数の各インスタンスが処理する最初のイベントに対してのみ表示されます。
[呼び出し] - ハンドラーコードの実行に要した時間を表します。
[オーバーヘッド] - Lambda ランタイムが次のイベントを処理するための準備に要する時間を表します。

新しいスタイルの関数セグメントには Invocation サブセグメントが含まれていません。代わりに、顧客サブセグメントが関数セグメントに直接アタッチされます。古いスタイルの関数セグメントと新しいスタイルの関数セグメントの構造の詳細については、「」を参照してくださいX-Ray トレースを理解する。

HTTP クライアントをインストルメント化し、SQL クエリを記録して、注釈とメタデータからカスタムサブセグメントを作成することもできます。詳細については、「AWS X-Ray デベロッパーガイド」の「AWS X-Ray SDK for Node.js」を参照してください。

料金

X-Ray トレースは、毎月、AWS 無料利用枠で設定された一定限度まで無料で利用できます。X-Ray の利用がこの上限を超えた場合は、トレースによる保存と取得に対する料金が発生します。詳細については、「AWS X-Ray 料金表」を参照してください。

ランタイムの依存関係をレイヤー (X-Ray SDK) に保存する

X-Ray SDK を使用して AWS SDK クライアントを関数コードに埋め込むと、デプロイパッケージが巨大になる可能性があります。関数コードを更新するたびにランタイムの依存関係がアップロードされないようにするには、X-Ray SDK を「Lambda レイヤー」にパッケージ化します。

次に、AWS X-Ray SDK for Node.js を保存している 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 が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ログ記録

TypeScript で構築