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

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

設定 Java 的 X-Ray SDK

Java 的 X-Ray 包括一個名SDKAWSXRay為提供全局記錄器的類。這是可以用來檢測程式碼的 TracingHandler。您可以設定全域記錄器，以自訂為來HTTP電建立區段的內容。AWSXRayServletFilter

服務外掛程式

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

外掛程式

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

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

  • Amazon ECS-ECSPlugin 添加容器 ID。

  • Amazon EKS — EKSPlugin 新增容器 ID、叢集名稱、網繭 ID 和 CloudWatch 日誌群組。

使用 Amazon EC2 和 Elastic Beanstalk 插件細分資源數據。

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

範例 src /主/爪/記分/ .java-記錄器 WebConfig
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());
  }
}

SDK也會使用外掛程式設定來設定區origin段上的欄位。這表示運行您的應用程序的 AWS 資源的類型。當您使用多個外掛程式時，SDK會使用下列解析度順序來決定原點： ElasticBeanstalk EKS> ECS > > EC2。

抽樣規則

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

會依照SDK定義規則的順序套用自訂規則。如果要求符合多個自訂規則，則只會SDK套用第一個規則。

注意

如果無法達到 X-Ray SDK 以取得取樣規則，則會回復為每秒第一個要求的預設本機規則，而每個主機的任何其他要求的百分之五。如果主機沒有呼叫取樣的權限APIs，或者無法連線至 X-Ray 精靈 (做為SDK. TCP API

您也可以配置SDK為從JSON文件載入取樣規則。對於無法使用 X-Ray 取樣的情況，SDK可以使用本機規則做為備份，或僅使用本機規則。

範例 採樣規則
{
  "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
  }
}

此範例定義了一個自訂規則和一個預設規則。自訂規則會套用百分之五的取樣率，而且沒有追蹤下限路徑的要求數目下/api/move/限。預設規則會每秒追蹤第一個要求，以及 10% 的額外要求。

在本機定義規則的缺點是，固定目標會由記錄器的每個執行個體獨立套用，而不是由 X-Ray 服務管理。當您部署更多主機時，固定費率會倍增，因此更難以控制記錄的資料量。

開啟時 AWS Lambda，您無法修改取樣率。如果您的函數是由已檢測的服務呼叫，則 Lambda 會記錄產生由該服務取樣之請求的呼叫。如果啟用主動追蹤且沒有追蹤標頭，Lambda 會做出取樣決策。

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

範例 src/主/爪/我的應用程序/. Java WebConfig-記錄器配置
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輸出到您的應用程序日誌。您可以在上啟用偵錯層級記錄，以將更詳細的記錄輸出SDK至應用程式記錄檔。有效的記錄層級為DEBUGINFOWARN、ERROR、、和FATAL。 FATAL日誌級別將所有日誌消息靜音，因為SDK不會在致命級別進行記錄。

範例 application.properties

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

logging.level.com.amazonaws.xray = DEBUG

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

將追蹤 ID 插入日誌

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

範例 完整的合格追蹤 ID

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

1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3

此功能可搭配使用 Java AWS X-Ray SDK 測試的 Java 應用程式使用，並支援下列記錄設定：

  • SLF4J前端API與登錄後端

  • SLF4J前端API與 Log4J2 後端

  • Log4J2 前端與 Log4J2 後端 API

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

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類別，該類別會自動將新的追蹤注IDs入SLF4JMDC。

    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類，該類將自動將新的完全限定跟踪注IDs入 SLF4JMDC.

    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 插入 future 的記錄陳述式中。 %X{}表示您正在使用提供的索引鍵從擷取值MDC。若要 PatternLayouts 在登入中進一步了解，請參閱PatternLayout。

Log4J2 backend

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

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

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

  2. 在中的%X{AWS-XRAY-TRACE-ID}任何位置插PatternLayout入，將追蹤 ID 插入 future 的記錄陳述式中。 %X{}表示您正在使用提供的索引鍵從擷取值MDC。要了解有關 Log4J2 PatternLayouts 的更多信息，請參閱模式佈局。
插入追蹤 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，或是記錄SQL攔截器傳送的查詢，以驗證子區段是否代表SQL查詢，如果是，則新增其他中繼資料。beforeEndSubsegment

若要查看完整的SegmentListener函數清單，請參閱 Java AWS X-Ray 記錄程式SDK的文件API。

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

範例 MySegmentListener. 爪哇
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 聲明
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
        .standard().withSegmentListener(new MySegmentListener());

環境變數

您可以使用環境變數來設定 Java SDK 的 X-Ray。支SDK援下列變數。

  • AWS_XRAY_CONTEXT_MISSING— 設定為當您RUNTIME_ERROR的檢測程式碼嘗試在沒有區段開啟時記錄資料時擲回例外狀況。

    有效值

    • RUNTIME_ERROR— 擲回執行階段例外狀況。

    • LOG_ERROR— 記錄錯誤並繼續 (預設值)。

    • IGNORE_ERROR— 忽略錯誤並繼續。

    當您嘗試在沒有要求開啟時執行的啟動程式碼中使用已檢測的用戶端，或在產生新執行緒的程式碼中使用已檢測的用戶端時，可能會發生與遺失區段或子區段相關的錯誤。

  • AWS_XRAY_DAEMON_ADDRESS— 設定 X-Ray 精靈監聽程式的主機和連接埠。默認情況下，SDK用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特定替代方案。支SDK援下列屬性：

  • 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.

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