本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
設定 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 插件細分資源數據。](images/scorekeep-PUTrules-segment-resources.png)
若要使用外掛程式,請在 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至應用程式記錄檔。有效的記錄層級為DEBUG
INFO
WARN
、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
請參閱下列標籤,以了解每個前端和每個後端的需求。
插入追蹤 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
.
如果同時設定了系統屬性和同等環境變數,則會使用環境變數的值。兩種方法都會覆寫程式碼中所設的值。