設定適用於 Java 的 X-Ray 開發套件 - AWS X-Ray
服務外掛程式抽樣規則日誌區段接聽程式環境變數系統屬性

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

設定適用於 Java 的 X-Ray 開發套件

適用於 Java 的 X-Ray 開發套件包含名為 的類別AWSXRay，可提供全域記錄器。這是可以用來檢測程式碼的 TracingHandler。您可以設定全域記錄器來自訂為傳入 HTTP 呼叫建立區段的 AWSXRayServletFilter。

服務外掛程式

使用 plugins 記錄託管您應用程式之服務的相關資訊。

外掛程式

  • Amazon EC2 – EC2Plugin 新增執行個體 ID、可用區域和 CloudWatch Logs 群組。

  • Elastic Beanstalk – ElasticBeanstalkPlugin 新增環境名稱、版本標籤和部署 ID。

  • Amazon ECS – ECSPlugin 新增容器 ID。

  • Amazon EKS – EKSPlugin 新增容器 ID、叢集名稱、Pod ID 和 CloudWatch Logs 群組。

使用 Amazon EC2 和 Elastic Beanstalk 外掛程式來分割資源資料。

若要使用外掛程式，請在 AWSXRayRecorderBuilder 上呼叫 withPlugin。

範例 src/main/java/scorekeep/WebConfig.java - 記錄器
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {
...
  static {
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());

    URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
    builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

    AWSXRay.setGlobalRecorder(builder.build());
  }
}

軟體開發套件也會使用外掛程式設定來設定區段上的 origin 欄位。這表示執行您應用程式 AWS 的資源類型。當您使用多個外掛程式時，開發套件會使用下列解析順序來判斷原始伺服器：ElasticBeanstalk > EKS > ECS > EC2。

抽樣規則

SDK 會使用您在 X-Ray 主控台中定義的抽樣規則來決定要記錄哪些請求。預設規則每秒追蹤第一個請求，以及所有傳送追蹤至 X-Ray 服務的任何其他請求的 5%。在 X-Ray 主控台中建立其他規則，以自訂為每個應用程式記錄的資料量。

軟體開發套件會依定義自訂規則的順序進行套用。如果請求符合多個自訂規則，軟體開發套件只會套用第一個規則。

注意

如果開發套件無法達到 X-Ray 以取得取樣規則，它會每秒還原為第一個請求的預設本機規則，以及每個主機任何額外請求的 5%。如果主機沒有呼叫取樣 APIs許可，或無法連線至 X-Ray 協助程式，而該常駐程式可做為 SDK 進行 API 呼叫的 TCP 代理，則可能會發生這種情況。

您也可以設定 SDK 以從 JSON 文件載入取樣規則。開發套件可以使用本機規則作為 X-Ray 取樣不可用的備份，或僅使用本機規則。

範例 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 會做出抽樣決策。

若要在 Spring 中提供備份規則，請在組態類別中使用 CentralizedSamplingStrategy 設定全域記錄器：

範例 src/main/java/myapp/WebConfig.java - 記錄器組態
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

@Configuration
public class WebConfig {

  static {
  AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

  URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
  builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

  AWSXRay.setGlobalRecorder(builder.build());
}

若是 Tomcat，請新增接聽程式以擴展 ServletContextListener，並在部署描述項中註冊接聽程式。

範例 src/com/myapp/web/Startup.java
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;

import java.net.URL;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

public class Startup implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent event) {
        AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());

        URL ruleFile = Startup.class.getResource("/sampling-rules.json");
        builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));

        AWSXRay.setGlobalRecorder(builder.build());
    }

    @Override
    public void contextDestroyed(ServletContextEvent event) { }
}
範例 WEB-INF/web.xml
...
  <listener>
    <listener-class>com.myapp.web.Startup</listener-class>
  </listener>

若僅要使用本機規則，請將 CentralizedSamplingStrategy 取代為 LocalizedSamplingStrategy。

builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));

日誌

根據預設，開發套件會將 ERROR層級訊息輸出到您的應用程式日誌。您可以在 SDK 上啟用偵錯層級記錄，將更詳細的日誌輸出至應用程式日誌檔案。有效的日誌層級為 DEBUG、INFO、ERROR、 WARN和 FATAL。FATAL日誌層級會靜音所有日誌訊息，因為 SDK 不會在嚴重層級進行日誌。

範例 application.properties

使用 logging.level.com.amazonaws.xray 屬性設定記錄日誌層級。

logging.level.com.amazonaws.xray = DEBUG

當您手動產生子區段時，可使用除錯日誌來識別問題，例如未結束的子區段。

將追蹤 ID 插入日誌

若要將您日誌陳述式公開給目前的追蹤 ID，您可以將此 ID 插入到映射的診斷內容 (MDC)。使用 SegmentListener 界面，會在區段生命週期事件期間從 X-Ray 記錄器呼叫方法。當區段或子區段開始時，合格的追蹤 ID 會透過金鑰 AWS-XRAY-TRACE-ID 注入至 MDC。當該區段結束時，該索引鍵即會從 MDC 中移除。這會公開正在使用的記錄程式庫追蹤 ID。當子區段結束時，其父 ID 會注入 MDC 中。

範例 完整的合格追蹤 ID

完整的合格 ID 會表示為 TraceID@EntityID

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

此功能適用於使用適用於 Java 的 AWS X-Ray 開發套件檢測的 Java 應用程式，並支援下列記錄組態：

  • SLF4J 前端 API 與 Logback 後端

  • SLF4J 前端 API 與 Log4J2 後端

  • Log4J2 前端 API 與 Log4J2 後端

請參閱下列標籤，以了解每個前端和每個後端的需求。

SLF4J Frontend

  1. 將以下 Maven 相依性新增到您的專案。

    <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-slf4j</artifactId>
    <version>2.11.0</version>
</dependency>

  2. 建置 AWSXRayRecorder 時包含 withSegmentListener 方法。這會新增 SegmentListener 類別，將新的追蹤 ID 自動插入 SLF4J MDC。

    SegmentListener 會採用選擇性字串做為參數來設定日誌陳述式的字首。您可以透過下列方式設定字首：

    • 無 – 使用預設AWS-XRAY-TRACE-ID字首。

    • 空白 – 使用空字串 （例如 "")。

    • 自訂 – 使用字串中定義的自訂字首。

    範例 AWSXRayRecorderBuilder 陳述式
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));
Log4J2 front end

  1. 將以下 Maven 相依性新增到您的專案。

    <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-log4j</artifactId>
    <version>2.11.0</version>
</dependency>

  2. 建置 AWSXRayRecorder 時包含 withSegmentListener 方法。這會新增 SegmentListener 類別，將新的完整合格追蹤 ID 自動注入 SLF4J MDC。

    SegmentListener 會採用選擇性字串做為參數來設定日誌陳述式的字首。您可以透過下列方式設定字首：

    • 無 – 使用預設AWS-XRAY-TRACE-ID字首。

    • 空白 – 使用空字串 （例如 "") 並移除字首。

    • 自訂 – 使用字串中定義的自訂字首。

    範例 AWSXRayRecorderBuilder 陳述式
    AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));
Logback backend

若要將追蹤 ID 插入到日誌事件中，您必須修改記錄器的 PatternLayout，這會格式化每個記錄陳述式。

  1. 尋找 patternLayout 的設定位置。您可透過編寫程式的方式，或透過 XML 組態檔案執行此作業。若要深入了解，請參閱 Logback 組態。

  2. 將 %X{AWS-XRAY-TRACE-ID} 插入到 patternLayout 的任何位置，可將追蹤 ID 插入未來的記錄陳述式。%X{} 表示您正在使用 MDC 提供的索引鍵擷取值。若要深入了解 Logback 中的 PatternLayout，請參閱 PatternLayout。

Log4J2 backend

  1. 尋找 patternLayout 的設定位置。您可透過編寫程式的方式，或透過以 XML、JSON、YAML 或屬性格式編寫的組態檔案執行此作業。

    若要深入了解如何透過組態檔案設定 Log4J2，請參閱組態。

    若要深入了解如何透過編寫程式的方式設定 Log4J2，請參閱透過編寫程式方式的組態。

  2. 將 %X{AWS-XRAY-TRACE-ID} 插入到 PatternLayout 的任何位置，可將追蹤 ID 插入未來的記錄陳述式。%X{} 表示您正在使用 MDC 提供的索引鍵擷取值。若要深入了解 Log4J2 中的 PatternLayout，請參閱模式配置。
插入追蹤 ID 範例

以下示範包含追蹤 ID 的修改後 PatternLayout 字串。追蹤 ID 會列印在執行緒名稱 (%t) 之後、日誌層級 (%-5p) 之前。

範例 插入 ID 的 PatternLayout
%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n

AWS X-Ray 會自動列印日誌陳述式中的金鑰和追蹤 ID，以便於剖析。以下顯示使用修改後 PatternLayout 的日誌說明。

範例 插入 ID 的日誌說明
2019-09-10 18:58:30.844 [nio-5000-exec-4]  AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here

記錄訊息本身以 %m 模式包裝，在呼叫記錄器時設定。

區段接聽程式

區段接聽程式是攔截生命週期事件的界面，例如 產生的區段開始和結束AWSXRayRecorder。區段接聽程式事件函數的實作可能是在透過 onBeginSubsegment 建立時，將相同的註釋新增至所有子區段、使用 afterEndSegment 將每個區段傳送到精靈後記錄訊息，或者透過 beforeEndSubsegment記錄由 SQL 攔截器傳送的查詢，以驗證子區段是否代表 SQL 查詢，如果是的話，則會新增額外的中繼資料。

若要查看SegmentListener函數的完整清單，請造訪AWS X-Ray 適用於 Java 的 記錄器開發套件 API 的文件。

下列範例顯示如何在建立 onBeginSubsegment 時將一致的註釋加入所有子區段，以及透過 afterEndSegment 在每個區段結尾列印記錄訊息。

範例 MySegmentListener.java
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
import com.amazonaws.xray.listeners.SegmentListener;

public class MySegmentListener implements SegmentListener {
    .....
    
    @Override
    public void onBeginSubsegment(Subsegment subsegment) {
        subsegment.putAnnotation("annotationKey", "annotationValue");
    }
    
    @Override
    public void afterEndSegment(Segment segment) {
        // Be mindful not to mutate the segment
        logger.info("Segment with ID " + segment.getId());
    }
}

在建立 AWSXRayRecorder 時參考此自訂區段接聽程式。

範例 AWSXRayRecorderBuilder statement
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new MySegmentListener());

環境變數

您可以使用環境變數來設定適用於 Java 的 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)。如果您已設定協助程式在不同的連接埠上接聽，或正在不同的主機上執行，請使用此變數。

    格式

    • 相同連接埠 – address:port

    • 不同的連接埠 – tcp:address:port udp:address:port

  • AWS_LOG_GROUP – 將日誌群組的名稱設定為與您的應用程式相關聯的日誌群組。如果您的日誌群組使用與您應用程式相同的 AWS 帳戶和區域，X-Ray 將使用此指定的日誌群組自動搜尋應用程式的區段資料。如需日誌群組的詳細資訊，請參閱使用日誌群組和串流。

  • AWS_XRAY_TRACING_NAME – 設定 SDK 用於區段的服務名稱。覆寫您在 servlet 篩選條件的區段命名策略中設定的服務名稱。

環境變數會覆寫程式碼中所設的同等系統屬性和值。

系統屬性

您可以將系統屬性做為環境變數的 JVM 專用替代方案。開發套件支援以下屬性：

  • com.amazonaws.xray.strategy.tracingName – 相當於 AWS_XRAY_TRACING_NAME。

  • com.amazonaws.xray.emitters.daemonAddress – 相當於 AWS_XRAY_DAEMON_ADDRESS。

  • com.amazonaws.xray.strategy.contextMissingStrategy – 相當於 AWS_XRAY_CONTEXT_MISSING。

如果同時設定了系統屬性和同等環境變數，則會使用環境變數的值。兩種方法都會覆寫程式碼中所設的值。