本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在多线程应用程序中的线程之间传递分段上下文
多线程处理

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

在您的应用程序中创建新线程时，`AWSXRayRecorder` 不会维护对当前分段或子分段[实体](https://docs.amazonaws.cn/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html)的引用。如果您在新话题中使用经过检测的客户端，SDK 会尝试写入不存在的区段，从而导致 [SegmentNotFoundException](https://docs.amazonaws.cn/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html).

为避免在开发过程中抛出异常，您可以为记录器配置一个[ContextMissingStrategy](https://docs.amazonaws.cn/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html)提醒它记录错误的。您可以使用代码配置策略 [SetContextMissingStrategy](https://docs.amazonaws.cn/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy))，也可以使用[环境变量](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)或[系统属性](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops)配置等效选项。

解决错误的一种方法是使用新分段：在您启动线程时调用 [beginSegment](https://docs.amazonaws.cn/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String))，并在您将其关闭时调用 [endSegment](https://docs.amazonaws.cn/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--)。如果您正在检测并非为响应 HTTP 请求而运行的代码，例如在您的应用程序启动时运行的代码，这很适合。

如果您使用多个线程来处理传入请求，您可以将当前分段或子分段传递到新线程，并将其提供给全局记录器。这样可以确保对于新线程中记录的信息，相关联的分段与针对该请求记录的其余信息的关联分段相同。一旦分段在新线程中可用，即可执行任何可使用 `segment.run(() -> { ... })` 方法访问该分段的上下文的可运行。

有关示例，请参阅 [在工作线程中使用检测的客户端](scorekeep-workerthreads.md)。

## 使用 X-Ray 进行异步编程


 适用于 Java 的 X-Ray SDK 可以在异步 Java 程序中使用[SegmentContextExecutors](https://docs.amazonaws.cn/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html)。 SegmentContextExecutor 实现了 Executor 接口，这意味着它可以传递到 a [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)的所有异步操作中。这样可以确保任何异步操作都将在其上下文中使用正确的分段执行。

**Example 示例 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());
```