AWS Node.js SDK用 X-Ray - AWS X-Ray
要件依存関係管理Node.js サンプル

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS Node.js SDK用 X-Ray

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

注記

X-Ray SDK for Node.js は、Node.js バージョン 14.x 以降でサポートされているオープンソースプロジェクトです。プロジェクトに従い、 で問題やプルリクエストを送信できます 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 関数ごとに 1 つのノードが含まれます。を追加することでSDK、関数コードを計測して、Lambda によって記録された関数セグメントにサブセグメントを追加できます。詳細については、「AWS Lambda および AWS X-Ray」を参照してください。

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

X-Ray SDK for Node.js は、HTTPウェブAPIsおよびSQLクエリへのダウンストリーム呼び出しの計測も提供します。SDKのキャプチャメソッドでHTTPクライアントをラップして、発信HTTP通話に関する情報を記録します。SQL クライアントの場合は、データベースタイプ のキャプチャメソッドを使用します。

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

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

注釈とメタデータ

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

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

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

要件

X-Ray SDK for Node.js には Node.js と以下のライブラリが必要です。

  • atomic-batcher – 1.0.2

  • cls-hooked – 4.2.2

  • pkginfo – 0.4.0

  • semver – 5.3.0

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

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

  • aws-sdk - 2.7.15

依存関係管理

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

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

~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
  ├─┬ aws-xray-sdk-core@3.3.3
  │ ├── @aws-sdk/service-error-classification@3.15.0
  │ ├── @aws-sdk/types@3.15.0
  │ ├─┬ @types/cls-hooked@4.3.3
  │ │ └── @types/node@15.3.0
  │ ├── atomic-batcher@1.0.2
  │ ├─┬ cls-hooked@4.2.2
  │ │ ├─┬ async-hook-jl@1.7.6
  │ │ │ └── stack-chain@1.3.7
  │ │ └─┬ emitter-listener@1.1.2
  │ │   └── shimmer@1.2.1
  │ └── semver@5.7.1
  ├── aws-xray-sdk-express@3.3.3
  ├── aws-xray-sdk-mysql@3.3.3
  └── aws-xray-sdk-postgres@3.3.3

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

~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3

アプリケーションに X-Ray の依存関係とバージョンが競合SDKする依存関係がある場合は、互換性を確保するために両方のバージョンがインストールされます。詳細については、依存関係の解決に関する公式NPMドキュメントを参照してください。

Node.js サンプル

Node.js の を使用して AWS X-Ray SDK、Node.js アプリケーションを通過するリクエスト end-to-end を表示します。