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

# 了解中代理资源的可观察性 AgentCore
<a name="observability-telemetry"></a>

本节定义了与代理监控和可观察性相关的会话、跟踪和跨度的概念。

**Topics**
+ [会话](#sessions)
+ [跟踪](#traces)
+ [跨度](#agent_spans)
+ [会话、跟踪和跨度之间的关系](#relationship)

## 会话
<a name="sessions"></a>

会话代表用户和代理之间的完整交互上下文。会话封装了整个对话或互动流程，维护了多个交换之间的状态和上下文。每个会话都有唯一的标识符，并记录了用户与代理互动的整个生命周期，从初始化到终止。

会话为代理提供以下功能：
+ 同一对话中多次互动的情境持久性
+ 用于维护用户特定信息的状态管理
+ 追踪对话历史记录，便于理解上下文
+ 互动期间的资源分配和管理
+ 隔离不同用户与同一个代理的交互

从可观察性的角度来看，会话提供了用户参与模式的高级视图，使您可以监控代理在指标、跟踪和跨度方面的性能，并了解用户在一段时间内和不同用例中如何与代理进行互动。

默认情况下， AgentCore 为运行 AgentCore 时中运行的代理提供一组会话级别的可观察性指标。您可以在亚马逊 CloudWatch 控制台的生成式 AI 可观测性页面上查看运行时指标。此页面提供各种图表和可视化效果，可帮助您解释代理的数据。 AgentCore 还会输出内存资源、网关资源和内置工具的一组默认指标。所有这些指标都可以在中查看 CloudWatch。除了提供的指标外，默认情况下还会为内存资源提供日志和跨度，通过分析代理代码，您可以捕获代理的自定义指标、日志和跨度，也可以在 CloudWatch 生成式 AI 可观测性页面上查看这些指标、日志和跨度。要了解更多信息，请参阅以下章节和[查看您的亚马逊 Bedrock AgentCore 代理](observability-view.md)的可观测性数据。

## 跟踪
<a name="traces"></a>

跟踪代表从代理调用开始的单个请求-响应周期的详细记录，可能包括对其他代理的额外调用。跟踪记录请求的完整执行路径，包括所有内部处理步骤、外部服务调用、决策点和资源利用率。每条跟踪都与特定的会话相关联，并提供对特定交互中代理行为的精细可见性。

跟踪包括以下代理组件：
+ 请求详情，包括时间戳、输入参数和上下文
+ 显示所执行操作顺序的处理步骤
+ 带有 input/output 参数和执行时间的工具调用
+ 资源利用率指标，例如处理时间
+ 错误信息，包括异常详细信息和恢复尝试
+ 响应生成细节和最终输出

从可观察性的角度来看，跟踪可以深入了解代理的内部运作，从而使您能够解决问题、优化性能并了解行为模式。通过分析跟踪数据，您可以识别瓶颈，检测异常，并验证您的代理在不同的场景和输入下是否按预期运行。

要收集跟踪数据，您需要使用开放遥测 Amazon 发行版 (ADOT) 对代理代码进行检测。要了解更多信息，请参阅[在代理代码中[启用可观察性和为外部托管的代理启用 AgentCore](observability-configure.md#observability-configure-3p)可观察性。 AgentCore-hosted ](observability-configure.md#observability-configure-custom)

## 跨度
<a name="agent_spans"></a>

跨度代表代理执行流程中离散的、可测量的工作单元。Span 可捕获请求处理期间发生的精细操作，从而详细了解构成完整跟踪的内部组件和步骤。每个跨度都有明确的开始和结束时间，从而为代理活动及其持续时间创建了精确的时间表。

跨度包括以下代理可观察性的基本属性：
+ 标识正在执行的特定功能或进程的操作名称
+ 时间戳标记操作的确切开始和结束时间
+ Parent-child 关系显示操作如何在更大的流程中嵌套
+ 标签和属性提供有关操作的上下文元数据
+ 标志着跨度生命周期内发生重大事件的事件
+ 指示成功、失败或其他完成状态的状态信息
+ 特定于操作的资源利用率指标

跨度在跟踪中形成分层结构，父跨度包括代表更精细操作的子跨度。例如，高级别 “流程用户查询” 跨度可能包含 “解析输入”、“检索上下文”、“生成响应” 和 “格式输出” 的子跨度。这种分层组织创建了详细的执行树，显示了代理内部的完整操作流程。

默认情况下，仅为内存资源 AgentCore 输出一组跨度数据。可以在 CloudWatch 日志和 CloudWatch 应用程序信号中查看这些数据。要记录代理或网关资源的跨度数据，您需要对代理进行检测。要了解更多信息，请参阅[在代理代码中[启用可观察性和为外部托管的代理启用 AgentCore](observability-configure.md#observability-configure-3p)可观察性。 AgentCore-hosted ](observability-configure.md#observability-configure-custom)

## 会话、跟踪和跨度之间的关系
<a name="relationship"></a>

会话、跟踪和跨度在代理的可观测性框架中形成了三层分层关系。一个会话包含多条轨迹，每条轨迹代表会话更广泛背景下的离散交互。反过来，每条跟踪都包含多个跨度，这些跨度捕捉了交互中的细粒度操作和步骤。这种分层结构允许您在不同的粒度级别上分析代理行为，从高级会话模式到中级交互流程，再到特定操作的详细执行路径。

这三个可观测性组件之间的关系可以可视化为：
+ 会话（最高级别）-代表完整的用户对话或互动上下文
+ 跟踪（中级）-代表会话中的个人请求-响应周期
+ 跨度（最低级别）-表示跟踪中的特定操作或步骤

这种多层关系实现了几种重要的可观测性功能：
+ 在更广泛的对话流程中对个人互动进行情境分析
+ 用户互动过程中相关请求的关联
+ 从会话级异常到跟踪级模式再到跨度级根本原因的渐进式故障排除
+ 在不同的时间和功能维度上进行全面的性能分析
+ 在对话中全面了解代理人的行为模式和演变
+ 通过跨度分析精确识别运营层面的性能瓶颈

虽然跟踪可以了解完整的请求-响应周期，但跨度可以更深入地了解这些周期的内部运作情况。跨度可以准确显示哪些操作消耗最多的时间、错误的起源以及不同组件在单个轨迹中如何相互作用。在排除复杂问题或优化复杂代理实施中的性能时，这种粒度尤其有价值。

通过在可观测性策略中利用会话、跟踪和跨度数据，您可以从多个细节层面全面了解代理的行为、性能和有效性。这种多层的可观测性方法支持持续改进、强大的故障排除以及对代理实施进行明智的优化，从高级对话模式到个人操作性能。