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

# 遥测设置和交付
<a name="supported-frameworks-telemetry"></a>

您的代理会发出跨度，亚马逊基岩 AgentCore 评估使用这些跨度来重建每个会话。有关如何 AgentCore 表示会话、跟踪和跨度，请参阅中的[了解代理资源的可观测性。 AgentCore ](observability-telemetry.md)

要为会话评分，该服务需要对话内容：模型提示、模型完成以及工具输入和输出。这些内容的位置取决于您的代理如何提供遥测数据，这正是本页的解释。

 **主题** 
+  [设置可观察性 ](#supported-frameworks-setup) 
+  [遥测传送模式 ](#supported-frameworks-telemetry-modes) 
  +  [统一遥测（推荐）](#supported-frameworks-telemetry-unified) 
  +  [分体遥测 ](#supported-frameworks-telemetry-split) 
+  [该服务从跨度读取的内容 ](#supported-frameworks-telemetry-spans) 
+  [参考](#supported-frameworks-telemetry-references) 
+  [样品代理 ](#supported-frameworks-samples) 

## 设置可观察性
<a name="supported-frameworks-setup"></a>

对代理进行仪表是生成评估服务可以读取的遥测数据的一部分。您的代理还必须启用可观察性，以便将其遥测数据导出到亚马逊。 CloudWatch完成以下步骤：

1.  **启用亚马逊 CloudWatch 交易搜索。**评估要求在两种交付模式下都使用它。请参阅[启用 AgentCore 可观察性](observability-configure.md#observability-configure-builtin)。

1.  **根据您的托管位置为代理**启用可观察性：
   +  **在 Amazon Bedrock AgentCore Runtime 上**：请参阅在代理代码中为 AgentCore-hosted 代理[启用可观察性。](observability-configure.md#observability-configure-custom)
   +  **在 AgentCore 运行时外托管**（亚马逊 ECS、亚马逊 EKS、 Amazon Lambda 或其他环境）：请参阅为外部托管的代理[启用可观察性。 AgentCore ](observability-configure.md#observability-configure-3p)您也可以在这里设置接收遥测数据的日志组。

1.  **检查您的代理使用哪种交付模式**，这样您就可以知道遥测的着陆点。您在 2026 年 7 月 20 日当天或之后创建的代理默认使用统一遥测，而您在该日期之前创建的代理使用分割遥测。统一遥测需要 ADOT 版本 0.18.0 或更高版本 ()。`aws-opentelemetry-distro>=0.18.0`早期版本向共享`aws/spans`日志组发送跨度。

   对于 AgentCore Runtime 上的代理，您可以使用`UNIFIED_TRACES_DESTINATION_ENABLED`环境变量切换模式：将其设置为`true`用于统一遥测或`false`分离遥测。有关环境变量、IAM 权限以及每个托管选项的完整程序，请参阅在 Amazon Bedrock AgentCore 运行时[托管的代理的 ](observability-configure.md#observability-configure-unified-traces) Span 目的地。

更改交付模式不会移动 AgentCore 已经交付的遥测数据。较旧的 Span 会保留在写入的日志组中，因此该服务仍会评估您在更改之前记录的会话。

## 遥测传送模式
<a name="supported-frameworks-telemetry-modes"></a>

AgentCore 以以下两种模式之一提供代理的遥测数据：
+  **统一遥测**（推荐）可将所有内容整合在一起。承载模型有效载荷的属性以及工具请求和响应保持不变，并且您的代理的所有遥测数据都集中到一个日志组。
+  **分离式遥测将两**者分开。 Amazon 发行版 OpenTelemetry (ADOT) 将这些属性从跨度移动到单独的记录中，这些记录会转到与跨度不同的日志组。

AgentCore 评估读取两种模式。在评估服务中，您不能在它们之间进行选择，无论哪种方式，相同的评估者都会给出相同的结果。我们建议使用统一遥测，该遥测适用于所有提供 AgentCore Runtime 的 Amazon 商业区域。

### 统一遥测（推荐）
<a name="supported-frameworks-telemetry-unified"></a>

使用统一遥测，您的所有代理的遥测数据都将归入一个日志组。跨度转到该`spans`日志组中的日志流，位于代理自己的日志和控制台输出旁边。该跨度保留了承载模型有效载荷以及工具请求和响应的属性，因此该服务会从跨度本身读取所需的一切。

![统一遥测：ADOT 将每个跨度及其内容发送到一个日志组](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/images/evaluations-unified-telemetry.png)


哪个日志组存放跨度取决于您托管代理的位置：
+  **在亚马逊 Bedrock AgentCore Runtime 上**：代理的日志组，`/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>`。 AgentCore 为你设置这个。
+  **在 AgentCore 运行时外部托管**：您在`OTEL_EXPORTER_OTLP_TRACES_HEADERS`环境变量中命名的日志组。

将跨度和日志保存在一个地方有助于评估之外的用处。您可以一起查看跟踪和日志，可以编写 Amazon 身份和访问管理 (IAM) 策略，为单个代理设置客户托管密钥加密，还可以导出代理通过订阅一个日志组生成的所有内容。

### 分体遥测
<a name="supported-frameworks-telemetry-split"></a>

通过分体遥测，ADOT 可将大型有效载荷从跨度中移除。当它导出每个跨度时，它会提取承载模型有效载荷以及工具请求和响应的属性，并将它们作为单独**的事件记录发送**，而跨度则保留其元数据和较小的属性。事件记录仅在此模式下存在，它们遵循 OpenTelemetry 事件惯例。

每条事件记录都通过共享`traceId`和链接回其跨度`spanId`，内容位于记录中`body`，例如在`body.input.messages`和中`body.output.messages`。

![拆分遥测：ADOT 将跨度和会话内容作为事件记录发送到代理日志组 aws/spans](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/images/evaluations-split-telemetry.png)


然后，这两种记录会流向不同的地方：
+  **跨度**转到共享`aws/spans`日志组。 CloudWatch 当您打开 “事务搜索” 时创建此日志组。
+  **事件记录**转到单独的日志组。在 AgentCore 运行时，这是代理的日志组，位于`otel-rt-logs`日志流中，它会为您 AgentCore 设置。在 AgentCore Runtime 之外，它是您在`OTEL_EXPORTER_OTLP_LOGS_HEADERS`环境变量中命名的日志组。

为了评估会话，该服务会从其事件记录中读取跨度并将其`aws/spans`与其事件记录进行匹配。

## 该服务从跨度读取的内容
<a name="supported-frameworks-telemetry-spans"></a>

对于会话中的每个跨度，该服务执行以下操作：

1. 根据框架设置的属性计算出跨度是什么样的。跨度可以是**调用代理跨度**（顶级代理运行）、**执行工具跨度**（单个工具调用）或**推理跨度**（单个模型调用）。

1. 读取其所需的值，例如用户提示、代理响应以及工具输入和输出。例如，用户提示来自代理输入中的用户角色消息，代理响应来自代理输出中的助手角色消息。

在两种交付模式下，标识跨度的属性始终保持在跨度上。只有对话内容会移动。内容在跨度内的位置还取决于您的工具库：大多数库将其记录为跨度属性，有些库将其作为事件附加到跨度上。对于每个库，每个框架的页面列出了识别属性，说出内容所在的位置，并显示了两种模式的示例跨度。

## 参考
<a name="supported-frameworks-telemetry-references"></a>

AgentCore 评估基于以下 OpenTelemetry 规范：
+  [追踪 OpenTelemetry 网站](https://opentelemetry.io/docs/specs/semconv/general/trace/)上的语义惯例：跨度和轨迹的结构及其含义。
+  [ OpenTelemetry 网站](https://opentelemetry.io/docs/specs/semconv/general/events/)上的事件语义惯例：事件记录的结构及其含义。
+  [Generative-AI GitHub 网站](https://github.com/open-telemetry/semantic-conventions-genai)上的语义约定：描述代理、模型和工具操作的`gen_ai.*`属性。

## 样品代理
<a name="supported-frameworks-samples"></a>

以下示例显示了如何对在亚马逊 Bedrock AgentCore Runtime 之外托管的 Strands 代理进行仪器测试。每个示例都 CloudWatch 使用 ADOT 将遥测数据导出到亚马逊。他们专注于可观察性设置，而不是评估 API。这些示例使用 Strands，但相同的托管和遥测导出模式适用于其他支持的框架，例如。 LangGraph
+  **亚马逊 EKS**：亚马逊EKS上的 EKS-hosted 代理[和 [ Strands代理](https://github.com/awslabs/agentcore-samples/tree/main/03-integrations/agents-hosted-outside-runtime/agents-on-eks)的可观察性](https://github.com/awslabs/agentcore-samples/tree/main/06-workshops/06-AgentCore-observability/06-Agentcore-observability-for-eks-hosted-agent)，均在网站上 GitHub 。
+  **亚马逊 ECS**： GitHub 网站上的亚马逊 ECS [上的](https://github.com/awslabs/agentcore-samples/tree/main/03-integrations/agents-hosted-outside-runtime/agents-on-ecs) Strands 代理。
+  ** Amazon Lambda**：网站[上 Amazon Lambda 中的](https://github.com/awslabs/agentcore-samples/tree/main/03-integrations/agents-hosted-outside-runtime/agents-on-aws-lambda/02-agent-in-lambda) Strands 代理。 GitHub