トレース AWS SDKによる X-Ray SDK for Node.jsの呼び出し

アプリケーションで AWS のサービス の呼び出しを行い、データの保存、キューへの書き込み、または通知の送信を行う場合、X-Ray SDK for Node.js によってサブセグメントの呼び出しダウンストリームが追跡されます。これらのサービス (例えば、Amazon S3 バケットまたは Amazon SQS キュー) 内でアクセスするトレースされた AWS のサービス およびリソースは、X-Ray コンソールのトレースマップではダウンストリームノードとして表示されます。

AWS SDK for JavaScript V2 または AWS SDK for JavaScript V3 で作成した AWS SDK クライアントを計測します。AWS SDK バージョンごとに、AWS SDK クライアントを計測する方法が異なります。

注記

現在、AWS X-Ray SDK for Node.js が AWS SDK for JavaScript V3 クライアントを計測するときに返されるセグメント情報は、V2 クライアントを計測する場合と比較して少なくなっています。例えば、DynamoDB への呼び出しを表すサブセグメントはテーブル名を返しません。トレースにこのセグメント情報が必要な場合は、AWS SDK for JavaScript V2 の使用を検討してください。

AWS SDK for JavaScript V2

aws-sdk 必須ステートメントを AWSXRay.captureAWS に対する呼び出しにラップすることで、すべての AWS SDK V2 クライアントを計測できます。

例 app.js - AWS SDK 計測

const AWS = AWSXRay.captureAWS(require('aws-sdk'));

個別のクライアントを計測するには、AWS SDK クライアントを AWSXRay.captureAWSClient に対する呼び出しにラップします。たとえば、AmazonDynamoDB クライアントを計測するには:

例 app.js - DynamoDB クライアント計測

    const AWSXRay = require('aws-xray-sdk');
...
    const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());

警告

captureAWS と captureAWSClient との両方を使用しないでください。これにより、サブセグメントが重複します。

ECMAScript モジュール (ESM) で TypeScript を使用して JavaScript コードをロードする場合は、次の例を使用してライブラリをインポートします。

例 app.js - AWS SDK 計測

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

ESM を使用してすべての AWS クライアントを計測するには、次のコードを使用します。

例 app.js - AWS SDK 計測

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
const XRAY_AWS = AWSXRay.captureAWS(AWS);
const ddb = new XRAY_AWS.DynamoDB();

すべてのサービスにおいて、X-Ray コンソールでコールされた API の名前を確認できます。サービスのサブセットの場合、X-Ray SDK はセグメントに情報を追加して、サービスマップでより細かく指定します。

たとえば、実装された DynamoDB クライアントでコールすると、SDK はテーブルをターゲットとするコールのセグメントにテーブル名を追加します。コンソールで、各テーブルはサービスマップ内に個別のノードとして表示され、テーブルをターゲットにしないコール用の汎用の DynamoDB ノードが表示されます。

例 項目を保存するための DynamoDB に対するコールのサブセグメント

{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}

名前付きリソースにアクセスしたとき、次のサービスをコールすると、サービスマップに追加のノードが作成されます。特定のリソースをターゲットとしないコールでは、サービスの汎用ノードが作成されます。

• Amazon DynamoDB – テーブル名

• Amazon Simple Storage Service – バケットとキー名

• Amazon Simple Queue Service – キュー名

AWS SDK for JavaScript V3

AWS SDK for JavaScript V3 はモジュール式なので、コードは必要なモジュールだけをロードします。このため、V3 は captureAWS メソッドをサポートしないため、すべての AWS SDK クライアントを計測することはできません。

ECMAScript Modules (ESM) で TypeScript を使用して JavaScript コードをロードする場合は、次の例を使用してライブラリをインポートできます。

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

AWSXRay.captureAWSv3Client メソッドを使用して各 AWS SDK クライアントを計測します。たとえば、AmazonDynamoDB クライアントを計測するには:

例 app.js - JavaScript V3 用 SDK を使用した DynamoDB クライアント計測

    const AWSXRay = require('aws-xray-sdk');
    const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
    const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));

AWS SDK for JavaScript V3 を使用する場合、テーブル名、バケット、キー名、キュー名などのメタデータは現在返されないため、AWS SDK for JavaScript V2 を使用して AWS SDK クライアントを計測する場合とは異なり、トレースマップに名前付きリソースごとの個別のノードは含まれません。

例 AWS SDK for JavaScript V3 を使用して項目を保存するための DynamoDB に対する呼び出しのサブセグメント

{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}