AWS X-Ray
開発者ガイド

X-Ray SDK for Node.js

X-Ray SDK for Node.js は、Express ウェブアプリケーションと Node.js Lambda 関数用のライブラリです。トレースデータを作成して X-Ray デーモンに送信するためのクラスとメソッドを提供します。トレースデータには、アプリケーションによって処理された受信 HTTP リクエストと、アプリケーションから AWS SDK または HTTP クライアントを使用して行われたダウンストリームサービスに対する呼び出しに関する情報が含まれています。

注記

X-Ray SDK for Node.js は、オープンソースプロジェクトです。プロジェクトに従って、GitHub github.com/aws/aws-xray-sdk-node で問題とプルリクエストを送信できます。

Express を使用する場合は、アプリケーションサーバーで SDK をミドルウェアとして追加し、受信リクエストをトレースします。ミドルウェアでは、トレース対象リクエストごとに「セグメント」を作成し、レスポンスが送信されるとセグメントを完了します。セグメントが開いている間、SDK クライアントのメソッドを使用してセグメントに情報を追加し、サブセグメントを作成してダウンストリーム呼び出しをトレースできます。また、SDK では、セグメントが開いている間にアプリケーションがスローする例外を自動的に記録します。

計測されたアプリケーションまたはサービスによって呼び出される Lambda 関数の場合、Lambda は トレースヘッダー を読み込み、サンプリングされたリクエストを自動的にトレースします。他の関数については、Lambda の設定 で受信リクエストのサンプルとトレースを行うことができます。いずれの場合も、Lambda はセグメントを作成し、X-Ray SDK に提供します。

注記

Lambda では、X-Ray SDK はオプションです。関数で使用しない場合、サービスマップには Lambda サービス用のノードと各 Lambda 関数用のノードが含まれます。SDK を追加すると、関数コードを計測して、Lambda によって記録された関数セグメントにサブセグメントを追加することができます。詳細については、「AWS Lambda および AWS X-Ray」を参照してください。

次に、X-Ray SDK for Node.js を使用して AWS SDK for JavaScript in Node.js クライアントを計測します。計測済みのクライアントを使用して、ダウンストリーム AWS のサービスやリソースに対して呼び出しを行うたびに、SDK はサブセグメントの呼び出しに関する情報を記録します。サービス内でアクセスする AWS のサービスとリソースは、サービスマップでダウンストリームノードとして表示され、個々の接続でエラーとスロットリングの問題を識別するのに役立ちます。

また、X-Ray SDK for Node.js では、HTTP ウェブ API と SQL クエリに対するダウンストリーム呼び出しの計測もできます。HTTP クライアントを SDK のキャプチャメソッドでラップして、送信 HTTP 呼び出しについての情報を記録します。SQL クライアントでは、データベースタイプのキャプチャメソッドを使用します。

ミドルウェアでは、受信リクエストにサンプリングルールを適用して、トレースするリクエストを決定します。X-Ray SDK for Node.js を設定してサンプリング動作を調整するか、アプリケーションで実行される AWS のコンピューティングリソースについての情報を記録できます。

アプリケーションが注釈やメタデータで行うリクエストや作業に関する追加情報を記録します。注釈は、フィルタ式で使用するためにインデックス化されたシンプルなキーと値のペアで、特定のデータが含まれているトレースを検索できます。メタデータのエントリは制約が緩やかで、JSON にシリアル化することが可能なオブジェクトと配列全体を記録できます。

注釈とメタデータ

注釈とメタデータは、X-Ray SDK でセグメントに追加する任意のテキストです。注釈はフィルタ式用にインデックス付けされます。メタデータはインデックス付けされませんが、X-Ray コンソールまたは API の raw セグメントに表示されます。X-Ray への読み取りアクセスを付与されたユーザーはだれでも、このデータを表示できます。

コードに多数の計測されたクライアントがある場合、単一のリクエストセグメントには計測されたクライアントで行われた呼び出しごとに 1 個の多数のサブセグメントを含めることができます。カスタムサブセグメントで、クライアント呼び出しをラップすることで、サブセグメントを整理してグループできます。関数全体またはコードの任意のセクションのサブセグメントを作成し、親セグメントにすべてのレコードを記述する代わりにサブセグメントにメタデータと注釈を記録できます。

SDK のクラスとメソッドに関するリファレンスドキュメントについては、AWS X-Ray SDK for Node.js API リファレンスを参照してください。

要件

X-Ray SDK for Node.js には Node.js および次のライブラリが必要です。

  • cls – 0.1.5

  • continuation-local-storage – 3.2.0

  • pkginfo – 0.4.0

  • underscore – 1.8.3

NPM を使用して SDK をインストールするときに、SDK ではこれらのライブラリを引き出します。

AWS SDK クライアントをトレースする場合、X-Ray SDK for Node.js では AWS SDK for JavaScript in Node.js の最小バージョンが必要です。

  • aws-sdk – 2.7.15

依存関係管理

X-Ray SDK for Node.js は NPM から入手できます。

ローカル開発の場合は、npm を使用してプロジェクトディレクトリに SDK をインストールします。

~/nodejs-xray$ npm install aws-xray-sdk nodejs-xray@0.0.0 ~/nodejs-xray └─┬ aws-xray-sdk@2.0.0 ├─┬ continuation-local-storage@3.2.0 │ ├─┬ async-listener@0.6.3 │ │ └── shimmer@1.0.0 │ └── emitter-listener@1.0.1 ├── moment@2.17.1 ├── pkginfo@0.4.0 ├── semver@5.3.0 ├── underscore@1.8.3 └─┬ winston@2.3.1 ├── async@1.0.0 ├── colors@1.0.3 ├── cycle@1.0.3 ├── eyes@0.1.8 ├── isstream@0.1.2 └── stack-trace@0.0.9

--save オプションを使用して、SDK を依存関係としてアプリケーションの package.json に保存します。

~/nodejs-xray$ npm install aws-xray-sdk --save nodejs-xray@0.0.0 ~/nodejs-xray └── aws-xray-sdk@2.0.0

このページの内容: