本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS 適用於 Node.js 的 X-Ray 開發套件
**注意**
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [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)。
適用於 Node.js 的 X-Ray 開發套件是 Express Web 應用程式和 Node.js Lambda 函數的程式庫，提供產生追蹤資料並將其傳送至 X-Ray 協助程式的類別和方法。追蹤資料包含應用程式提供的傳入 HTTP 請求，以及應用程式使用 AWS SDK 或 HTTP 用戶端對下游服務發出的呼叫的相關資訊。
**注意**
適用於 Node.js 的 X-Ray 開發套件是 Node.js 14.x 版及更高版本支援的開放原始碼專案。您可以關注專案，並在 GitHub 上提交問題與提取 (pull) 請求：[github.com/aws/aws-xray-sdk-node](https://github.com/aws/aws-xray-sdk-node)
若您使用 Express，請在您的應用程式伺服器上從[將軟體開發套件新增為中介軟體](xray-sdk-nodejs-middleware.md)開始，來追蹤傳入請求。中介軟體會為每個追蹤的請求建立[區段](xray-concepts.md#xray-concepts-segments)，並在傳送回應時完成區段。當區段開啟時，您可以使用軟體開發套件用戶端的方法，將資訊新增到區段，並建立子區段以追蹤下游呼叫。軟體開發套件也會在區段為開啟時自動記錄應用程式擲回的例外狀況。
對於經檢測的應用程式或服務呼叫的 Lambda 函數，Lambda 會自動讀取[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)並追蹤取樣的請求。對於其他 函數，您可以[設定 Lambda](xray-services-lambda.md) 來取樣和追蹤傳入的請求。無論哪種情況，Lambda 都會建立客群並將其提供給 X-Ray 開發套件。
**注意**
在 Lambda 上，X-Ray 開發套件是選用的。如果您未在函數中使用它，您的服務映射仍會包含 Lambda 服務的節點，以及每個 Lambda 函數的節點。透過新增 SDK，您可以檢測函數程式碼，將子區段新增至 Lambda 記錄的函數區段。如需詳細資訊，請參閱[AWS Lambda 而且 AWS X-Ray](xray-services-lambda.md)。
接著，使用適用於 Node.js 的 X-Ray 開發套件在 [Node.js 用戶端中檢測適用於 JavaScript 的 AWS 開發套件。](xray-sdk-nodejs-awssdkclients.md)每當您使用經檢測的用戶端呼叫下游 AWS 服務 或資源時，開發套件會在子區段中記錄有關呼叫的資訊。 AWS 服務 而您在服務中存取的資源會在追蹤地圖上顯示為下游節點，以協助您識別錯誤並調節個別連線的問題。
適用於 Node.js 的 X-Ray 開發套件也提供對 HTTP Web APIs和 SQL 查詢的下游呼叫檢測。[將您的 HTTP 用戶端包裝在軟體開發套件的擷取方法中](xray-sdk-nodejs-httpclients.md)，來記錄傳出 HTTP 呼叫的相關資訊。針對 SQL 用戶端，[請使用您資料庫類型的擷取方法](xray-sdk-nodejs-sqlclients.md)。
中介軟體會將抽樣規則套用到傳入請求，判斷要追蹤的請求。您可以[設定適用於 Node.js 的 X-Ray 開發套件](xray-sdk-nodejs-configuration.md)來調整取樣行為，或記錄應用程式執行所在的 AWS 運算資源相關資訊。
使用[註釋與中繼資料](xray-sdk-nodejs-segment.md)，記錄應用程式所做的請求和工作等其他資訊。註釋是簡單的鍵/值對，系統會為其建立索引以用於[篩選條件表達式](xray-console-filters.md)，因此您可以搜尋包含特定資料的追蹤。中繼資料項目的限制性較低，可以記錄整個物件和陣列，任何可以序列化為 JSON 的項目。
**標註與中繼資料**
註釋和中繼資料是您使用 X-Ray SDK 新增至客群的任意文字。註釋會編製索引，以便與篩選條件表達式搭配使用。中繼資料不會編製索引，但可以使用 X-Ray 主控台或 API 在原始區段中檢視。您授予 X-Ray 讀取存取權的任何人都可以檢視此資料。
當程式碼中有很多經過檢測的用戶端時，單一請求區段可能包含大量子區段，每個使用經檢測用戶端進行的呼叫都有一個子區段。您可以將用戶端呼叫包裝在[自訂子區段](xray-sdk-nodejs-subsegments.md)中，以組織和群組子區段。您可以為整個函數或任何部分的程式碼建立自訂子區段，並記錄子區段上的中繼資料和註釋，而不必寫入父區段上的所有項目。
如需開發套件類別和方法的參考文件，請參閱適用於 [AWS X-Ray Node.js 的開發套件 API 參考](https://docs.aws.amazon.com//xray-sdk-for-nodejs/latest/reference)。
## 要求
適用於 Node.js 的 X-Ray 開發套件需要 Node.js 和下列程式庫：
+ `atomic-batcher` – 1.0.2
+ `cls-hooked` – 4.2.2
+ `pkginfo` – 0.4.0
+ `semver` – 5.3.0
軟體開發套件會在您使用 NPM 安裝它時提取這些程式庫。
若要追蹤 AWS SDK 用戶端，適用於 Node.js 的 X-Ray 開發套件需要 Node.js 中適用於 JavaScript 的 AWS 開發套件最低版本。
+ `aws-sdk` – 2.7.15
## 相依性管理
適用於 Node.js 的 X-Ray 開發套件可從 NPM 取得。
+ **套件** – [https://www.npmjs.com/package/aws-xray-sdk](https://www.npmjs.com/package/aws-xray-sdk)
針對本機開發，請在您的專案目錄中使用 npm 安裝軟體開發套件。
```
~/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` 選項來在您應用程式的 `package.json` 中將軟體開發套件做為依存項目儲存。
```
~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3
```
如果您的應用程式有任何相依性，其版本與 X-Ray 開發套件的相依性衝突，則會安裝這兩個版本以確保相容性。如需詳細資訊，請參閱[官方 NPM 文件以取得相依性解析](http://npm.github.io/how-npm-works-docs/npm3/how-npm3-works.html)。
## Node.js 樣本
使用適用於 Node.js 的 AWS X-Ray SDK，end-to-end檢視。
+ GitHub 上的 [Node.js 範例應用程式](https://github.com/aws-samples/aws-xray-sdk-node-sample)。