本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用適用於 Java 的 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 開發套件來追蹤應用程式在 Amazon EC2 或 Amazon ECS 中的 EC2 執行個體上提供的傳入 HTTP 請求。 AWS Elastic Beanstalk
使用 `Filter` 檢測傳入的 HTTP 請求。當您將 X-Ray servlet 篩選條件新增至應用程式時，適用於 Java 的 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**
+ [將追蹤篩選條件新增至應用程式 (Tomcat)](#xray-sdk-java-filters-tomcat)
+ [將追蹤篩選條件新增至應用程式 (Spring)](#xray-sdk-java-filters-spring)
+ [設定區段命名策略](#xray-sdk-java-filters-naming)
## 將追蹤篩選條件新增至應用程式 (Tomcat)
若是 Tomcat，請將 `` 新增至您專案的 `web.xml` 檔案。使用 `fixedName` 參數，指定要套用至針對傳入請求建立之區段的[服務名稱](#xray-sdk-java-filters-naming)。
**Example WEB-INF/web.xml - Tomcat**
```
AWSXRayServletFilter
com.amazonaws.xray.javax.servlet.AWSXRayServletFilter
fixedName
MyApp
AWSXRayServletFilter
*
```
## 將追蹤篩選條件新增至應用程式 (Spring)
若是 Spring，請將 `Filter` 新增至您的 `WebConfig` 類別。以字串形式將區段名稱傳遞給 [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) 建構函數。
**Example src/main/java/myapp/WebConfig.java - Spring**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter("Scorekeep");
}
}
```
## 設定區段命名策略
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`，以不同名稱識別每個子網域的區段，在服務映射上產生三個服務節點。如果您的應用程式收到主機名稱與模式不相符的請求，您會在服務映射上看到具有您指定之備用名稱的第四個節點。
若要為所有請求區段使用相同的名稱，請如[上一節](#xray-sdk-java-filters-tomcat)所述，在初始化 servlet 篩選條件時指定您應用程式的名稱。這與透過呼叫`SegmentNamingStrategy.fixed()`並傳遞給建構函數來建立固定的 [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html) [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) 具有相同的效果。
**注意**
您可以使用 `AWS_XRAY_TRACING_NAME` [環境變數](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)來覆寫您在程式碼中定義的預設服務名稱。
動態命名策略可定義主機名稱應相符的模式，以及如果 HTTP 請求中的主機名稱不符合模式時要使用的預設名稱。若要在 Tomcat 中動態命名區段，請分別使用 `dynamicNamingRecognizedHosts` 和 `dynamicNamingFallbackName` 來定義模式和預設名稱。
**Example WEB-INF/web.xml - 使用動態命名的 Servlet 篩選條件**
```
AWSXRayServletFilter
com.amazonaws.xray.javax.servlet.AWSXRayServletFilter
dynamicNamingRecognizedHosts
*.example.com
dynamicNamingFallbackName
MyApp
AWSXRayServletFilter
*
```
對於 Spring，透過呼叫 建立動態 [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)`SegmentNamingStrategy.dynamic()`，並將其傳遞給`AWSXRayServletFilter`建構函數。
**Example src/main/java/myapp/WebConfig.java - 使用動態命名的 Servlet 篩選條件**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
import [com.amazonaws.xray.strategy.SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com"));
}
}
```