在多執行緒應用程式之間傳遞區段內容

注意

End-of-support通知 – 在 2027 年 2 月 25 日， AWS X-Ray 將停止支援 AWS X-Ray SDKs 和協助程式。2027 年 2 月 25 日之後，您將不再收到更新或版本。如需支援時間表的詳細資訊，請參閱 X-Ray SDK 和協助程式終止支援時間表。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱從 X-Ray 檢測遷移至 OpenTelemetry 檢測。

當您在應用程式中建立新執行緒時，AWSXRayRecorder 不會維持目前區段或子區段實體的參考。若您在新執行緒中使用受檢測的用戶端，軟體開發套件會嘗試寫入不存在的區段，且會導致 SegmentNotFoundException。

若要避免在開發期間拋出異常，您可以使用 ContextMissingStrategy 設定記錄器，告知其改而記錄錯誤。您可以使用 SetContextMissingStrategy 在程式碼中設定策略，或是使用環境變數或系統屬性來設定相等選項。

其中一種處理錯誤的方法是透過在啟動執行緒時呼叫 beginSegment 來使用新區段，以及在關閉時呼叫 endSegment。若您要檢測並非針對回應 HTTP 請求而執行的程式碼，這種方法可以正常運作，就像在應用程式啟動時執行的程式碼。

若您使用多個執行緒來處理傳入請求，您可以將目前區段或子區段傳遞至新執行緒，並將它提供給全域記錄器。這可確保在記錄該請求的其餘資訊時，於新執行緒中記錄的資訊會與相同區段建立關聯。區段在新執行緒中可用後，您可以使用 segment.run(() -> { ... })方法執行可存取該區段內容的任何可執行項目。

如需範例，請參閱在工作者執行緒中使用受檢測用戶端。

搭配非同步程式設計使用 X-Ray

適用於 Java 的 X-Ray 開發套件可用於具有 SegmentContextExecutors 的非同步 Java 程式。SegmentContextExecutor 實作執行器界面，這表示它可以傳遞到 CompletableFuture 的所有非同步操作。這可確保任何非同步操作都會在其內容中使用正確的區段執行。

範例 App.java 範例：將 SegmentContextExecutor 傳遞至 CompletableFuture

DynamoDbAsyncClient client = DynamoDbAsyncClient.create();

AWSXRay.beginSegment();

// ...

client.getItem(request).thenComposeAsync(response -> {
    // If we did not provide the segment context executor, this request would not be traced correctly.
    return client.getItem(request2);
}, SegmentContextExecutors.newSegmentContextExecutor());