翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS Node.js 用 X-Ray SDK
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
X-Ray SDK for Node.js は、Express ウェブアプリケーションと Node.js Lambda 関数用のライブラリです。トレースデータを作成して X-Ray デーモンに送信するためのクラスとメソッドを提供します。トレースデータには、アプリケーションによって提供される受信 HTTP リクエストに関する情報と、アプリケーションが AWS SDK または HTTP クライアントを使用してダウンストリームサービスに対して行う呼び出しが含まれます。
**注記**
X-Ray SDK for Node.js は、Node.js バージョン 14.x 以降でサポートされるオープンソースプロジェクトです。プロジェクトに従って、GitHub [github.com/aws/aws-xray-sdk-node](https://github.com/aws/aws-xray-sdk-node) で問題とプルリクエストを送信できます。
Express を使用する場合は、アプリケーションサーバーで [SDK をミドルウェアとして追加し](xray-sdk-nodejs-middleware.md)、受信リクエストをトレースします。ミドルウェアでは、トレース対象リクエストごとに「[セグメント](xray-concepts.md#xray-concepts-segments)」を作成し、レスポンスが送信されるとセグメントを完了します。セグメントが開いている間、SDK クライアントのメソッドを使用してセグメントに情報を追加し、サブセグメントを作成してダウンストリーム呼び出しをトレースできます。また、SDK では、セグメントが開いている間にアプリケーションがスローする例外を自動的に記録します。
インストルメント済みアプリケーションまたはサービスによって呼び出される Lambda 関数の場合、Lambda は [トレースヘッダー](xray-concepts.md#xray-concepts-tracingheader) を読み取り、サンプリングされたリクエストを自動的にトレースします。その他の関数については、[Lambda の設定](xray-services-lambda.md) から受信リクエストのサンプリングとトレースを行うことができます。いずれの場合も、Lambda はセグメントを作成し、X-Ray SDK に提供します。
**注記**
Lambda では、X-Ray SDK はオプションです。関数でこれを使用しない場合、サービスマップには Lambda サービスのノードと Lambda 関数ごとに 1 つのノードが含まれます。SDK を追加することで、関数コードをインストルメントして、Lambda で記録された関数セグメントにサブセグメントを追加することができます。詳細については「[AWS Lambda および AWS X-Ray](xray-services-lambda.md)」を参照してください。
次に、X-Ray SDK for Node.js を使用して、[Node.js クライアントで AWS SDK for JavaScript を計測します](xray-sdk-nodejs-awssdkclients.md)。計測されたクライアントを使用してダウンストリーム AWS のサービス またはリソースを呼び出すたびに、SDK は呼び出しに関する情報をサブセグメントに記録します。 AWS のサービス サービス内でアクセスするリソースは、トレースマップにダウンストリームノードとして表示され、個々の接続でエラーやスロットリングの問題を特定するのに役立ちます。
また、X-Ray SDK for Node.js では、HTTP ウェブ API と SQL クエリに対するダウンストリーム呼び出しの計測もできます。[HTTP クライアントを SDK のキャプチャメソッドでラップ](xray-sdk-nodejs-httpclients.md)して、送信 HTTP 呼び出しについての情報を記録します。SQL クライアントでは、[データベースタイプのキャプチャメソッドを使用](xray-sdk-nodejs-sqlclients.md)します。
ミドルウェアでは、受信リクエストにサンプリングルールを適用して、トレースするリクエストを決定します。[X-Ray SDK for Node.js を設定](xray-sdk-nodejs-configuration.md)して、サンプリング動作を調整したり、アプリケーションが実行される AWS コンピューティングリソースに関する情報を記録したりできます。
アプリケーションが[注釈やメタデータ](xray-sdk-nodejs-segment.md)で行うリクエストや作業に関する追加情報を記録します。注釈は、[フィルタ式](xray-console-filters.md)で使用するためにインデックス化されたシンプルなキーと値のペアで、特定のデータが含まれているトレースを検索できます。メタデータのエントリは制約が緩やかで、JSON にシリアル化できるオブジェクトと配列全体を記録できます。
**注釈とメタデータ**
注釈およびメタデータとは、X-Ray SDK を使用してセグメントに追加する任意のテキストです。注釈は、フィルタ式用にインデックス付けされます。メタデータはインデックス化されませんが、X-Ray コンソールまたは API を使用して raw セグメントで表示できます。X-Ray への読み取りアクセスを許可した人は誰でも、このデータを表示できます。
コードに多数の計測されたクライアントがある場合、単一のリクエストセグメントには計測されたクライアントで行われた呼び出しごとに 1 個の多数のサブセグメントを含めることができます。[カスタムサブセグメント](xray-sdk-nodejs-subsegments.md)で、クライアント呼び出しをラップすることで、サブセグメントを整理してグループできます。関数全体またはコードの任意のセクションのサブセグメントを作成し、親セグメントにすべてのレコードを記述する代わりにサブセグメントにメタデータと注釈を記録できます。
SDK のクラスとメソッドに関するリファレンスドキュメントについては、[AWS X-Ray SDK for Node.js API リファレンス](https://docs.aws.amazon.com//xray-sdk-for-nodejs/latest/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
NPM を使用して SDK をインストールするときに、SDK ではこれらのライブラリを引き出します。
AWS SDK クライアントをトレースするには、X-Ray SDK for Node.js で AWS SDK for JavaScript in Node.js の最小バージョンが必要です。
+ `aws-sdk` - 2.7.15
## 依存関係管理
The X-Ray SDK for Node.js は NPM から入手できます。
+ **パッケージ** – [https://www.npmjs.com/package/aws-xray-sdk](https://www.npmjs.com/package/aws-xray-sdk)
ローカル開発の場合は、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 ドキュメンテーション](http://npm.github.io/how-npm-works-docs/npm3/how-npm3-works.html)を参照してください。
## Node.js サンプル
AWS X-Ray SDK for Node.js を使用して、Node.js アプリケーションを通過するリクエストのend-to-endビューを取得します。
+ GitHub 上の [Node.js サンプルアプリケーション](https://github.com/aws-samples/aws-xray-sdk-node-sample)。