X-Ray SDK for Node.js を使用して受信リクエストをトレースします。

X-Ray SDK for Node.js を使用して、Amazon EC2、AWS Elastic Beanstalk、または Amazon ECS の EC2 インスタンスで Express アプリケーションおよび Restify アプリケーションが提供する受信 HTTP リクエストをトレースできます。

X-Ray SDK for Node.js は Express フレームワークおよび Restify フレームワークを使用するアプリケーションのミドルウェアを提供します。X-Ray ミドルウェアをアプリケーションに追加すると、X-Ray SDK for Node.js によってサンプリングされた各リクエストのセグメントが作成されます。このセグメントには、時間、メソッド、HTTP リクエストの処理などが含まれます。追加の計測により、このセグメントでサブセグメントが作成されます。

注記

AWS Lambda関数では、Lambda は、サンプリングされた各リクエストのセグメントを作成します。詳細については、「AWS Lambda および AWS X-Ray」を参照してください。

各セグメントには、サービスマップ内のアプリケーションを識別する名前があります。セグメントの名前は静的に指定することも、受信リクエストのホストヘッダーに基づいて動的に名前を付けるように SDK を設定することもできます。動的ネーミングでは、リクエスト内のドメイン名に基づいてトレースをグループ化でき、名前が予想されるパターンと一致しない場合（たとえば、ホストヘッダーが偽造されている場合）、デフォルト名を適用できます。

転送されたリクエスト

ロードバランサーまたは他の仲介者がアプリケーションにリクエストを転送する場合、X-Ray は、クライアントの IP をIP パケットの送信元 IP からではなく、リクエストのX-Forwarded-Forヘッダーから取得します。転送されたリクエストについて記録されたクライアント IP は偽造される可能性があるため、信頼されるべきではありません。

リクエストが転送されると、それを示す追加フィールドが SDK によってセグメントに設定されます。セグメントのフィールド x_forwarded_for が true に設定されている場合、クライアント IP が HTTP リクエストの X-Forwarded-For ヘッダーから取得されます。

メッセージハンドラーは、次の情報が含まれる http ブロックを使用して、各受信リクエスト用にセグメントを作成します。

• HTTP メソッド – GET、POST、PUT、DELETE、その他。

• クライアントアドレス – リクエストを送信するクライアントの IP アドレス。

• レスポンスコード – 完了したリクエストの HTTP レスポンスコード。

• タイミング – 開始時間 (リクエストが受信された時間) および終了時間 (レスポンスが送信された時間)。

• ユーザーエージェント — リクエストからのuser-agent

• コンテンツの長さ — レスポンスからのcontent-length

Express を使用した受信リクエストのトレース

Express ミドルウェアを使用するには、SDK クライアントを初期化して、ルートを定義する前に express.openSegment 関数によって返されたミドルウェアを使用します。

例 app.js - Express

var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));

app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());

ルートを定義した後、express.closeSegment の出力を図のように使用して X-Ray SDK for Node.js によって返されたエラーを処理します。

Restify を使用した受信リクエストのトレース

Restify ミドルウェアを使用するには、SDK クライアントを初期化し、enable を実行します。Restify サーバーおよびセグメント名を渡します。

例 app.js - Restify

var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');

var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));

server.get('/', function (req, res) {
  res.render('index');
});

セグメント命名ルールの設定

AWS X-Rayはサービス名を使用してアプリケーションを識別し、他のアプリケーション、データベース、外部 API、およびAWSアプリケーションが使用するリソースと区別します。X-Ray SDK が受信リクエストのセグメントを生成すると、アプリケーションのサービス名がセグメントの名前フィールドに記録されます。

X-Ray SDK では、HTTP リクエストヘッダーのホスト名の後にセグメントの名前を指定できます。ただし、このヘッダーは偽造され、サービスマップに予期しないノードが発生する可能性があります。偽造されたホストヘッダーを持つリクエストによって SDK がセグメントの名前を間違えないようにするには、受信リクエストのデフォルト名を指定する必要があります。

アプリケーションが複数のドメインのリクエストを処理する場合、動的ネーミングストラテジーを使用してセグメント名にこれを反映するように SDK を設定できます。動的ネーミングストラテジーにより、SDK は予想されるパターンに一致するリクエストにホスト名を使用し、そうでないリクエストにデフォルト名を適用できます。

たとえば、3 つのサブドメイン（www.example.com,api.example.com,およびstatic.example.com）に対してリクエストを処理する単一のアプリケーションがあるとします。動的ネーミングストラテジーをパターン *.example.com で使用して、異なる名前を持つ各サブドメインのセグメントを識別することができます。結果的にはサービスマップ上に 3 つのサービスノードを作成することになります。アプリケーションがパターンと一致しないホスト名のリクエストを受信すると、指定したフォールバック名を持つ 4 番目のノードがサービスマップに表示されます。

すべてのリクエストセグメントに対して同じ名前を使用するには、前のセクションで示すとおり、ミドルウェアを初期化するときに、アプリケーションの名前を指定します。

注記

コードで定義したデフォルトのサービス名は、AWS_XRAY_TRACING_NAME 環境変数で上書きできます。

動的な命名戦略は、ホスト名と一致するようパターンを定義し、HTTP リクエストのホスト名がパターンと一致しない場合はデフォルトの名前を使用します。動的にセグメントに命名するには、AWSXRay.middleware.enableDynamicNaming を使用します。

例 app.js - 動的セグメントの名前

リクエストのホスト名がパターン *.example.com と一致する場合は、そのホスト名を使用します。それ以外の場合は、MyApp を使用します。

var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
AWSXRay.middleware.enableDynamicNaming('*.example.com');
        
app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());