本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Node.js
**注意**
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：
+ [AWS Distro for OpenTelemetry JavaScript](xray-js-opentel-sdk.md) – 透過 [AWS Distro for OpenTelemetry Collector](https://aws-otel.github.io/docs/getting-started/collector) AWS X-Ray， AWS 提供一組開放原始碼程式庫，用於將相關指標和追蹤傳送至多個 AWS 監控解決方案，包括 Amazon CloudWatch 和 Amazon OpenSearch Service。
+ [AWS X-Ray 適用於 Node.js 的 SDK](xray-sdk-nodejs.md) – 一組程式庫，用於透過 X-Ray [協助程式產生和傳送追蹤至 X-Ray](xray-daemon.md)。
如需詳細資訊，請參閱[選擇 AWS Distro for OpenTelemetry 和 X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing)。
# AWS Distro for OpenTelemetry JavaScript
使用 AWS Distro for OpenTelemetry (ADOT) JavaScript，您可以檢測您的應用程式一次，並將相關指標和追蹤傳送至多個 AWS 監控解決方案，包括 Amazon CloudWatch AWS X-Ray和 Amazon OpenSearch Service。搭配 AWS Distro for OpenTelemetry 使用 X-Ray 需要兩個元件：啟用 *OpenTelemetry SDK* 以搭配 X-Ray 使用，以及啟用 *AWS Distro for OpenTelemetry Collector* 以搭配 X-Ray 使用。
若要開始使用，請參閱 [AWS Distro for OpenTelemetry JavaScript 文件](https://aws-otel.github.io/docs/getting-started/javascript-sdk)。
**注意**
所有伺服器端 Node.js 應用程式都支援 ADOT JavaScript。ADOT JavaScript 無法從瀏覽器用戶端將資料匯出至 X-Ray。
如需搭配 AWS AWS X-Ray 和其他 使用 Distro for OpenTelemetry 的詳細資訊 AWS 服務，請參閱 [AWS Distro for OpenTelemetry](https://aws-otel.github.io/) 或 [AWS Distro for OpenTelemetry 文件](https://aws-otel.github.io/docs/introduction)。
如需語言支援和用量的詳細資訊，請參閱 [AWS GitHub 上的可觀測性](https://github.com/aws-observability)。
# 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)。
# 設定適用於 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 開發套件，以包含應用程式執行服務的相關資訊、修改預設抽樣行為，或新增適用於特定路徑請求的抽樣規則。
**Topics**
+ [服務外掛程式](#xray-sdk-nodejs-configuration-plugins)
+ [抽樣規則](#xray-sdk-nodejs-configuration-sampling)
+ [日誌](#xray-sdk-nodejs-configuration-logging)
+ [X-Ray 協助程式地址](#xray-sdk-nodejs-configuration-daemon)
+ [環境變數](#xray-sdk-nodejs-configuration-envvars)
## 服務外掛程式
使用 `plugins` 記錄託管您應用程式之服務的相關資訊。
**外掛程式**
+ Amazon EC2 – `EC2Plugin` 新增執行個體 ID、可用區域和 CloudWatch Logs 群組。
+ Elastic Beanstalk – `ElasticBeanstalkPlugin` 新增環境名稱、版本標籤和部署 ID。
+ Amazon ECS – `ECSPlugin` 新增容器 ID。
若要使用外掛程式，請使用 `config`方法設定適用於 Node.js 的 X-Ray 開發套件用戶端。
**Example app.js - 外掛程式**
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);
```
軟體開發套件也會使用外掛程式設定來設定區段上的 `origin` 欄位。這表示執行您應用程式 AWS 的資源類型。當您使用多個外掛程式時，軟體開發套件會使用下列解析順序來判斷原始伺服器：ElasticBeanstalk > EKS > ECS > EC2。
## 抽樣規則
SDK 會使用您在 X-Ray 主控台中定義的抽樣規則來決定要記錄哪些請求。預設規則每秒追蹤第一個請求，以及所有傳送追蹤至 X-Ray 服務的任何其他請求的 5%。[在 X-Ray 主控台中建立其他規則](xray-console-sampling.md)，以自訂為每個應用程式記錄的資料量。
軟體開發套件會依定義自訂規則的順序套用自訂規則。如果請求符合多個自訂規則，軟體開發套件只會套用第一個規則。
**注意**
如果開發套件無法達到 X-Ray 以取得取樣規則，它會每秒還原為第一個請求的預設本機規則，以及每個主機任何額外請求的 5%。如果主機沒有呼叫取樣 APIs許可，或無法連線到 X-Ray 協助程式，該常駐程式可做為 SDK 進行 API 呼叫的 TCP 代理，就可能發生這種情況。
您也可以設定 SDK 從 JSON 文件載入抽樣規則。開發套件可以在 X-Ray 取樣無法使用的情況下，使用本機規則做為備份，或僅使用本機規則。
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
此範例會定義一個自訂規則和預設規則。自訂規則會套用 5% 的取樣率，沒有追蹤 下路徑的最低請求數`/api/move/`。預設規則會追蹤每秒的第一個請求和 10% 的額外請求。
在本機定義規則的缺點是，固定目標是由記錄器的每個執行個體獨立套用，而不是由 X-Ray 服務管理。當您部署更多主機時，固定速率會倍增，因此更難控制記錄的資料量。
在 上 AWS Lambda，您無法修改取樣率。如果您的函數是由 檢測服務呼叫，則 Lambda 將記錄產生該服務取樣之請求的呼叫。如果啟用主動追蹤且不存在追蹤標頭，Lambda 會做出抽樣決策。
若要設定備份規則，請指示適用於 Node.js 的 X-Ray 開發套件使用 從 檔案載入取樣規則`setSamplingRules`。
**Example app.js - 檔案的抽樣規則**
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.middleware.setSamplingRules('sampling-rules.json');
```
您也可以在程式碼中定義規則，然後將其做為物件傳遞給 `setSamplingRules`。
**Example app.js - 物件的抽樣規則**
```
var AWSXRay = require('aws-xray-sdk');
var rules = {
"rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ],
"default": { "fixed_target": 1, "rate": 0.1 },
"version": 1
}
AWSXRay.middleware.setSamplingRules(rules);
```
若要僅使用本機規則，請呼叫 `disableCentralizedSampling`。
```
AWSXRay.middleware.disableCentralizedSampling()
```
## 日誌
若要記錄軟體開發套件的輸出，請呼叫 `AWSXRay.setLogger(logger)`，其中 `logger` 是提供標準記錄日誌方法的物件 (`warn`、`info` 等)。
根據預設，軟體開發套件會使用主控台物件上的標準方法，將錯誤訊息記錄到主控台。您可以使用 `AWS_XRAY_DEBUG_MODE`或 `AWS_XRAY_LOG_LEVEL`環境變數來設定內建記錄器的日誌層級。如需有效日誌層級值的清單，請參閱[環境變數](#xray-sdk-nodejs-configuration-envvars)。
如果您想要為日誌提供不同的格式或目的地，您可以向 SDK 提供自己的記錄器界面實作，如下所示。您可以使用任何實作此界面的物件。這表示許多日誌程式庫，例如 Winston，都可以直接使用並傳遞至 SDK。
**Example app.js - 日誌記錄**
```
var AWSXRay = require('aws-xray-sdk');
// Create your own logger, or instantiate one using a library.
var logger = {
error: (message, meta) => { /* logging code */ },
warn: (message, meta) => { /* logging code */ },
info: (message, meta) => { /* logging code */ },
debug: (message, meta) => { /* logging code */ }
}
AWSXRay.setLogger(logger);
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
```
請在執行其他組態方法前呼叫 `setLogger`，確保擷取來自這些操作的輸出。
## X-Ray 協助程式地址
如果 X-Ray 協助程式接聽 以外的連接埠或主機`127.0.0.1:2000`，您可以設定適用於 Node.js 的 X-Ray 開發套件，將追蹤資料傳送至不同的地址。
```
AWSXRay.setDaemonAddress('host:port');
```
您可以透過名稱或 IPv4 地址指定主機。
**Example app.js - 精靈地址**
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('daemonhost:8082');
```
若您設定精靈針對 TCP 和 UDP 接聽不同連接埠，您可以在精靈地址設定中同時指定它們。
**Example app.js - 位於不同連接埠的精靈地址**
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');
```
您也可以透過使用 `AWS_XRAY_DAEMON_ADDRESS` [環境變數](#xray-sdk-nodejs-configuration-envvars)來設定精靈地址。
## 環境變數
您可以使用環境變數來設定適用於 Node.js 的 X-Ray 開發套件。軟體開發套件支援以下變數。
+ `AWS_XRAY_CONTEXT_MISSING` – 設定為 `RUNTIME_ERROR` 以在未開啟區段時，檢測程式碼嘗試記錄資料時擲回例外狀況。
**有效值**
+ `RUNTIME_ERROR` – 擲回執行時間例外狀況。
+ `LOG_ERROR` – 記錄錯誤並繼續 （預設）。
+ `IGNORE_ERROR` – 忽略錯誤並繼續。
當您嘗試在未開啟請求時執行的啟動程式碼中使用經檢測用戶端，或在產生新執行緒的程式碼中，可能會發生與缺少區段或子區段相關的錯誤。
+ `AWS_XRAY_DAEMON_ADDRESS` – 設定 X-Ray 協助程式接聽程式的主機和連接埠。根據預設，軟體開發套件會使用 `127.0.0.1:2000` 進行追蹤資料 (UDP) 和取樣 (TCP)。如果您已設定協助程式在[不同的連接埠上接聽](xray-daemon-configuration.md)，或在不同的主機上執行，請使用此變數。
**格式**
+ **相同連接埠** – `address:port`
+ **不同的連接埠** – `tcp:address:port udp:address:port`
+ `AWS_XRAY_DEBUG_MODE` – 將 設定為 `TRUE`，以設定 SDK 將日誌輸出至 主控台的`debug`關卡。
+ `AWS_XRAY_LOG_LEVEL ` – 設定預設記錄器的日誌層級。有效值為`debug`、`info`、`warn`、`error`、`silent`。當 AWS\$1XRAY\$1DEBUG\$1MODE 模式設定為 `TRUE` 時，會忽略此值。
+ `AWS_XRAY_TRACING_NAME` – 設定軟體開發套件用於區段的服務名稱。覆寫您[在 Express 中介軟體上設定](xray-sdk-nodejs-middleware.md)的區段名稱。
# 使用適用於 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 and Restify 應用程式在 Amazon EC2 或 Amazon ECS 中的 EC2 執行個體上提供的傳入 HTTP 請求。 AWS Elastic Beanstalk
適用於 Node.js 的 X-Ray 開發套件為使用 Express 和 Restify 架構的應用程式提供中介軟體。當您將 X-Ray 中介軟體新增至應用程式時，適用於 Node.js 的 X-Ray 開發套件會為每個取樣請求建立區段。此區段包括時間、方法，以及 HTTP 請求的處置方式。其他檢測會在此區段上建立子區段。
**注意**
對於 AWS Lambda 函數，Lambda 會為每個取樣請求建立區段。如需詳細資訊，請參閱[AWS Lambda 而且 AWS X-Ray](xray-services-lambda.md)。
每個區段都有一個名稱，可在服務映射中識別您的應用程式。區段可以靜態命名，或者您可以設定 SDK 根據傳入請求中的主機標頭動態命名。動態命名可讓您根據請求中的網域名稱來分組追蹤，並在名稱不符合預期模式時套用預設名稱 （例如，如果主機標頭是偽造的）。
**轉送的請求**
如果負載平衡器或其他中介裝置轉送請求到您的應用程式，X-Ray 會從請求中的 `X-Forwarded-For`標頭取得用戶端 IP，而不是從 IP 封包中的來源 IP 取得用戶端 IP。為轉送請求記錄的用戶端 IP 可能是偽造的，因此不應受信任。
轉送請求時，開發套件會在區段中設定額外的欄位來表示這一點。如果區段包含`x_forwarded_for`設為 的欄位`true`，用戶端 IP 會從 HTTP 請求中的 `X-Forwarded-For`標頭取得。
訊息處理常式會使用 `http` 區塊為每個傳入的請求建立區段，其中包含以下資訊：
+ **HTTP 方法** – GET、POST、PUT、DELETE 等。
+ **用戶端地址** – 傳送請求之用戶端的 IP 地址。
+ **回應碼** – 已完成請求的 HTTP 回應碼。
+ **時間** – 開始時間 （收到請求的時間） 和結束時間 （傳送回應的時間）。
+ **使用者代理程式** — 來自請求`user-agent`的 。
+ **內容長度** — `content-length`來自回應的 。
**Topics**
+ [使用 Express 追蹤傳入的請求](#xray-sdk-nodejs-middleware-express)
+ [使用 Restify 追蹤傳入的請求](#xray-sdk-nodejs-middleware-restify)
+ [設定區段命名策略](#xray-sdk-nodejs-middleware-naming)
## 使用 Express 追蹤傳入的請求
若要使用 Express 中介軟體，請初始化軟體開發套件用戶端，並使用油 `express.openSegment` 函數傳回的中介軟體，再定義您的路由。
**Example 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`，如圖所示，來處理適用於 Node.js 的 X-Ray 開發套件傳回的任何錯誤。
## 使用 Restify 追蹤傳入的請求
若要使用 Restify 中介軟體，請初始化軟體開發套件用戶端並執行 `enable`。將它您的 Restify 伺服器和區段名稱傳遞給它。
**Example 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 使用*服務名稱*來識別您的應用程式，並將其與您的應用程式使用的其他應用程式、資料庫、外部 APIs AWS 和資源區分開來。當 X-Ray SDK 為傳入請求產生區段時，它會在區段的名稱欄位中記錄應用程式的服務[名稱](xray-api-segmentdocuments.md#api-segmentdocuments-fields)。
X-Ray SDK 可以在 HTTP 請求標頭中的主機名稱之後命名區段。不過，此標頭可以偽造，這可能會導致服務映射中出現非預期的節點。若要防止 SDK 因具有偽造主機標頭的請求而不正確地命名區段，您必須指定傳入請求的預設名稱。
如果您的應用程式為多個網域提供請求，您可以將 SDK 設定為使用動態命名策略，以在區段名稱中反映這一點。動態命名策略可讓軟體開發套件針對符合預期模式的請求使用主機名稱，並將預設名稱套用至不符合的請求。
例如，您可能有一個應用程式向三個子網域提供請求：`www.example.com`、 `api.example.com`和 `static.example.com`。您可以使用動態命名策略搭配 模式`*.example.com`，以不同名稱識別每個子網域的區段，在服務映射上產生三個服務節點。如果您的應用程式收到主機名稱不符合模式的請求，您會在服務地圖上看到具有您指定之備用名稱的第四個節點。
若要為所有請求區段使用相同的名稱，請如上一節所述，在初始化中介軟體時指定您應用程式的名稱。
**注意**
您可以使用 `AWS_XRAY_TRACING_NAME` [環境變數](xray-sdk-nodejs-configuration.md#xray-sdk-nodejs-configuration-envvars)來覆寫您在程式碼中定義的預設服務名稱。
動態命名策略可定義主機名稱應相符的模式，以及如果 HTTP 請求中的主機名稱不符合模式時要使用的預設名稱。若要動態命名區段，請使用 `AWSXRay.middleware.enableDynamicNaming`。
**Example 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());
```
# 使用適用於 Node.js 的 X-Ray AWS 開發套件追蹤 SDK 呼叫
**注意**
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)。
當您的應用程式呼叫 AWS 服務 來存放資料、寫入佇列或傳送通知時，適用於 Node.js 的 X-Ray 開發套件會在[子區段](xray-sdk-nodejs-subsegments.md)中追蹤下游的呼叫。您在這些服務中存取的追蹤 AWS 服務和資源 （例如 Amazon S3 儲存貯體或 Amazon SQS 佇列），會在 X-Ray 主控台的追蹤地圖上顯示為下游節點。
您透過 [適用於 JavaScript 的 AWS SDK V2](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html) 或 [適用於 JavaScript 的 AWS SDK V3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html) 建立的檢測 AWS SDK 用戶端。每個 AWS SDK 版本都提供用於檢測 AWS SDK 用戶端的不同方法。
**注意**
目前，與檢測 V2 用戶端相比，適用於 Node.js 的 AWS X-Ray SDK 在檢測 適用於 JavaScript 的 AWS SDK V3 用戶端時傳回的區段資訊較少。例如，代表對 DynamoDB 呼叫的子區段不會傳回資料表名稱。如果您在追蹤中需要此區段資訊，請考慮使用 適用於 JavaScript 的 AWS SDK V2。
------
#### [ 適用於 JavaScript 的 AWS SDK V2 ]
您可以在對 的呼叫中包裝`aws-sdk`您的需求陳述式，以檢測所有 AWS SDK V2 用戶端`AWSXRay.captureAWS`。
**Example app.js - AWS SDK 檢測**
```
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
```
若要檢測個別用戶端，請在呼叫 時包裝 AWS SDK 用戶端`AWSXRay.captureAWSClient`。例如，若要檢測 `AmazonDynamoDB` 用戶端：
**Example app.js - DynamoDB 用戶端檢測**
```
const AWSXRay = require('aws-xray-sdk');
...
const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
```
**警告**
請勿將 `captureAWS` 和 `captureAWSClient` 一起使用。這會導致重複的子區段。
如果您想要使用 [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) 搭配 [ECMAScript 模組](https://nodejs.org/api/esm.html) (ESM) 載入JavaScript程式碼，請使用下列範例來匯入程式庫：
**Example app.js - AWS SDK 檢測**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
若要使用 ESM 檢測所有 AWS 用戶端，請使用下列程式碼：
**Example app.js - AWS SDK 檢測**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
const XRAY_AWS = AWSXRay.captureAWS(AWS);
const ddb = new XRAY_AWS.DynamoDB();
```
對於所有 服務，您可以在 X-Ray 主控台中查看名為 的 API 名稱。對於服務子集，X-Ray SDK 會將資訊新增至區段，以在服務映射中提供更精細的服務。
例如，當您使用經檢測的 DynamoDB 用戶端進行呼叫時，軟體開發套件會將資料表名稱新增至以資料表為目標的呼叫區段。在 主控台中，每個資料表會在服務映射中顯示為個別節點，並針對非資料表目標的呼叫使用一般 DynamoDB 節點。
**Example 呼叫 DynamoDB 以儲存項目的子區段**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
您存取具名資源時，對以下服務的呼叫會在服務地圖中建立額外節點。未針對特定資源的呼叫，則會建立服務的一般節點。
+ **Amazon DynamoDB** – 資料表名稱
+ **Amazon Simple Storage Service** – 儲存貯體和金鑰名稱
+ **Amazon Simple Queue Service** – 佇列名稱
------
#### [ 適用於 JavaScript 的 AWS SDK V3 ]
適用於 JavaScript 的 AWS SDK V3 是模組化的，因此您的程式碼只會載入所需的模組。因此，由於 V3 不支援 `captureAWS`方法，因此無法檢測所有 AWS SDK 用戶端。
如果您想要使用 TypeScript 搭配 ECMAScript 模組 (ESM) 載入 JavaScript 程式碼，您可以使用下列範例來匯入程式庫：
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
使用 `AWSXRay.captureAWSv3Client`方法檢測每個 AWS SDK 用戶端。例如，若要檢測 `AmazonDynamoDB` 用戶端：
**Example app.js - 使用適用於 Javascript V3 的 SDK 進行 DynamoDB 用戶端檢測**
```
const AWSXRay = require('aws-xray-sdk');
const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));
```
使用 適用於 JavaScript 的 AWS SDK V3 時，資料表名稱、儲存貯體和金鑰名稱或佇列名稱等中繼資料目前不會傳回，因此追蹤映射不會像使用 適用於 JavaScript 的 AWS SDK V2 檢測 AWS SDK 用戶端時一樣包含每個具名資源的離散節點。
**Example 使用 適用於 JavaScript 的 AWS SDK V3 時，呼叫 DynamoDB 以儲存項目的子區段**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
------
# 使用適用於 Node.js 的 X-Ray 開發套件追蹤對下游 HTTP Web 服務的呼叫
**注意**
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)。
當您的應用程式呼叫微服務或公有 HTTP APIs，您可以使用適用於 Node.js 的 X-Ray 開發套件用戶端來檢測這些呼叫，並將 API 做為下游服務新增至服務圖表。
將 `http`或 `https`用戶端傳遞至適用於 Node.js 的 X-Ray 開發套件`captureHTTPs`方法，以追蹤傳出呼叫。
**注意**
使用協力廠商 HTTP 要求程式庫 (例如 Axios 或 Superagent) 的呼叫會透過 [`captureHTTPsGlobal()` API](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/module-http_p.html) 支援，並在使用原生 `http` 模組時，仍會追蹤這些呼叫。
**Example app.js - HTTP 用戶端**
```
var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));
```
若要啟用所有 HTTP 用戶端上的追蹤，請在載入 `http` 前呼叫 `captureHTTPsGlobal`。
**Example app.js - HTTP 用戶端 (全域)**
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');
```
當您檢測對下游 Web API 的呼叫時，適用於 Node.js 的 X-Ray 開發套件會記錄子區段，其中包含 HTTP 請求和回應的相關資訊。X-Ray 使用子區段來產生遠端 API 的推斷區段。
**Example 下游 HTTP 呼叫的子區段**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example 下游 HTTP 呼叫的推斷區段**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# 使用適用於 Node.js 的 X-Ray 開發套件追蹤 SQL 查詢
**注意**
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 開發套件用戶端方法中包裝 SQL 用戶端，以檢測 SQL 資料庫查詢。
+ **PostgreSQL** – `AWSXRay.capturePostgres()`
```
var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
var client = new pg.Client();
```
+ **MySQL** – `AWSXRay.captureMySQL()`
```
var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
...
var connection = mysql.createConnection(config);
```
當您使用受檢測用戶端進行 SQL 查詢時，適用於 Node.js 的 X-Ray 開發套件會在子區段中記錄連線及查詢的相關資訊。
## 在 SQL 子區段中包含其他資料
您可以將其他資訊新增至針對 SQL 查詢產生的子區段，只要它對應至允許清單的 SQL 欄位即可。例如，若要在子區段中記錄已淨化的 SQL 查詢字串，您可以將其直接新增至子區段的 SQL 物件。
**Example 將 SQL 指派給子區段**
```
const queryString = 'SELECT * FROM MyTable';
connection.query(queryString, ...);
// Retrieve the most recently created subsegment
const subs = AWSXRay.getSegment().subsegments;
if (subs & & subs.length > 0) {
var sqlSub = subs[subs.length - 1];
sqlSub.sql.sanitized_query = queryString;
}
```
如需允許清單 SQL 欄位的完整清單，請參閱《 *AWS X-Ray 開發人員指南*》中的 [SQL 查詢](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-sql)。
# 使用適用於 Node.js 的 X-Ray 開發套件產生自訂子區段
子區段會延伸追蹤的[區段](xray-concepts.md#xray-concepts-segments)，其中包含為了處理請求而完成之工作的詳細資訊。每次您與經檢測的用戶端進行呼叫時，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)。
若要為呼叫下游服務的函數建立自訂子區段，請使用 `captureAsyncFunc` 函數。
**Example app.js - 快速自訂子區段**
```
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) {
var host = 'api.example.com';
AWSXRay.captureAsyncFunc('send', function(subsegment) {
sendRequest(host, function() {
console.log('rendering!');
res.render('index');
subsegment.close();
});
});
});
app.use(AWSXRay.express.closeSegment());
function sendRequest(host, cb) {
var options = {
host: host,
path: '/',
};
var callback = function(response) {
var str = '';
response.on('data', function (chunk) {
str += chunk;
});
response.on('end', function () {
cb();
});
}
http.request(options, callback).end();
};
```
在此範例中，應用程式會為針對 `sendRequest` 函數的呼叫建立名為 `send` 的自訂子區段。`captureAsyncFunc` 會在其發出的非同步呼叫完成時傳遞您必須在回撥函數中關閉的子區段。
針對同步函數，您可以使用 `captureFunc` 函數，自動在函數區塊完成執行後關閉子區段。
當您在區段或其他子區段中建立子區段時，適用於 Node.js 的 X-Ray 開發套件會為其產生 ID，並記錄開始時間和結束時間。
**Example 使用中繼資料的子區段**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
## 自訂 Lambda 子區段
開發套件設定為在偵測到在 Lambda 中執行時自動建立預留位置外觀區段。若要建立基本子區段，以在 X-Ray 追蹤地圖上建立單一`AWS::Lambda::Function`節點，請呼叫 並重新利用外觀區段。如果您使用新 ID 手動建立新區段 (在共用追蹤 ID、父系 ID 和抽樣決策時)，您將能夠傳送新區段。
**Example app.js - 手動自訂子區段**
```
const segment = AWSXRay.getSegment(); //returns the facade segment
const subsegment = segment.addNewSubsegment('subseg');
...
subsegment.close();
//the segment is closed by the SDK automatically
```
# 使用適用於 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)。
您可以使用註釋和中繼資料記錄有關請求、環境或應用程式的其他資訊。您可以將註釋和中繼資料新增至 X-Ray 開發套件建立的區段，或新增至您建立的自訂子區段。
**註釋**是具有字串、數字或布林值的鍵值對。註釋會編製索引，以便與[篩選條件表達式](xray-console-filters.md)搭配使用。使用標記記錄您想要用來在主控台將追蹤分組的資料，或是在呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 時使用標記。
**中繼資料**是索引鍵/值對，可以具有任何類型的值，包括物件和清單，但不會編製索引以與篩選條件表達式搭配使用。使用中繼資料記錄您希望儲存在追蹤中的其他資料，但不需要搭配搜尋使用。
除了註釋和中繼資料，您也可以在區段上[記錄使用者 ID 字串](#xray-sdk-nodejs-segment-userid)。區段會將使用者 ID 記錄在單獨的欄位中，並建立索引以用於搜尋。
**Topics**
+ [使用適用於 Node.js 的 X-Ray 開發套件記錄註釋](#xray-sdk-nodejs-segment-annotations)
+ [使用適用於 Node.js 的 X-Ray 開發套件記錄中繼資料](#xray-sdk-nodejs-segment-metadata)
+ [使用適用於 Node.js 的 X-Ray 開發套件記錄使用者 IDs](#xray-sdk-nodejs-segment-userid)
## 使用適用於 Node.js 的 X-Ray 開發套件記錄註釋
針對您想要建立索引以用於搜尋的區段或子區段，請使用標註來記錄這些區段上的資訊。
**註釋要求**
+ **金鑰** – X-Ray 註釋的金鑰最多可有 500 個英數字元。您不能使用點或句點以外的空格或符號 ( 。 )
+ **值** – X-Ray 註釋的值最多可有 1，000 個 Unicode 字元。
+ **註釋**數量 – 每個追蹤最多可以使用 50 個註釋。
**記錄標註**
1. 取得目前區段或子區段的參考。
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. 使用字串索引鍵、布林值、數字或字串值，呼叫 `addAnnotation`。
```
document.addAnnotation("mykey", "my value");
```
下列範例示範如何使用包含點的`putAnnotation`字串索引鍵和布林值、數字或字串值來呼叫 。
```
document.putAnnotation("testkey.test", "my value");
```
軟體開發套件會將標註以鍵/值對記錄在區段文件中的 `annotations` 物件內。若使用相同鍵呼叫 `addAnnotation` 兩次，則會覆寫之前在相同區段或子區段上記錄的值。
若要尋找具有具有特定值註釋的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `annotation[key]`關鍵字。
**Example app.js - 標註**
```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
var item = {
'email': {'S': req.body.email},
'name': {'S': req.body.name},
'preview': {'S': req.body.previewAccess},
'theme': {'S': req.body.theme}
};
var seg = AWSXRay.getSegment();
seg.addAnnotation('theme', req.body.theme);
ddb.putItem({
'TableName': ddbTable,
'Item': item,
'Expected': { email: { Exists: false } }
}, function(err, data) {
...
```
## 使用適用於 Node.js 的 X-Ray 開發套件記錄中繼資料
針對您不想要建立索引以用於搜尋的區段，請使用中繼資料來記錄這些區段或子區段上的資訊。中繼資料值可以是字串、數字、布林值，或可序列化為 JSON 物件或陣列的任何其他物件。
**記錄中繼資料**
1. 取得目前區段或子區段的參考。
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. 使用字串鍵、布林值、數字、字串或物件值，以及字串命名空間，呼叫 `addMetadata`。
```
document.addMetadata("my key", "my value", "my namespace");
```
或
只使用鍵和值呼叫 `addMetadata`。
```
document.addMetadata("my key", "my value");
```
若您沒有指定命名空間，軟體開發套件會使用 `default`。若使用相同鍵呼叫 `addMetadata` 兩次，則會覆寫之前在相同區段或子區段上記錄的值。
## 使用適用於 Node.js 的 X-Ray 開發套件記錄使用者 IDs
記錄請求區段上的使用者 ID 以識別傳送請求的使用者。此操作與 AWS Lambda 函數不相容，因為 Lambda 環境中的區段不可變。`setUser` 呼叫只可套用至區段，而非子區段。
**記錄使用者 ID**
1. 取得目前區段或子區段的參考。
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. 使用傳送請求之使用者的字串 ID 呼叫 `setUser()`。
```
var user = 'john123';
AWSXRay.getSegment().setUser(user);
```
您可以呼叫 `setUser`，以在 Express 應用程式開始處理請求時馬上記錄使用者 ID。如果您只要使用區段來設定使用者 ID，可以將呼叫鏈結為單行。
**Example app.js - 使用者 ID**
```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var uuidv4 = require('uuid/v4');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
var userId = uuidv4();
var item = {
'userId': {'S': userId},
'email': {'S': req.body.email},
'name': {'S': req.body.name}
};
var seg = AWSXRay.getSegment().setUser(userId);
ddb.putItem({
'TableName': ddbTable,
'Item': item,
'Expected': { email: { Exists: false } }
}, function(err, data) {
...
```
若要尋找使用者 ID 的追蹤，請在[篩選條件表達](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html)式中使用 `user`關鍵字。