# 跨度、事件记录和遥测信号
<a name="supported-frameworks-telemetry"></a>

Amazon Bedrock AgentCore 评估会处理两个遥测信号，以了解您的代理的行为：
+  **跨度**描述单个操作。Span 包含有关操作的元数据：其名称、范围、时间戳和属性。跨度还可能包含对话内容，或者该内容可能存在于单独的事件记录中。
+  **事件记录**在`body`字段中包含有效载荷内容：模型、工具和代理的输入和输出。通过共享`traceId`和`spanId`将事件记录与其跨度相关联。事件记录遵循 OpenTelemetry 事件惯例。有关更多信息，请参阅[参考资料](#supported-frameworks-telemetry-references)。

要评估会话，服务需要跨度以及它们的相关事件记录（如果适用）。对于每个跨度，该服务会执行以下操作：

1. 根据特定于框架的属性标识跨度的类型。有关详细信息，请参阅每个框架的页面。

1. 读取所需的值，例如用户提示、代理响应以及工具输入和输出。这些值来自跨度的属性或其相关的事件记录。

 **主题** 
+  [ADOT 是如何拆分遥测的](#supported-frameworks-telemetry-collection) 
+  [存储跨度和事件记录的位置](#supported-frameworks-telemetry-location) 
+  [服务读取内容的位置](#supported-frameworks-telemetry-extraction) 
+  [参考](#supported-frameworks-telemetry-references) 

## ADOT 是如何拆分遥测的
<a name="supported-frameworks-telemetry-collection"></a>

**当你的代理使用 AWS 发行版 OpenTelemetry (ADOT) 运行时，遥测就会被拆分。****导出跨度时，ADOT 会从跨度属性中提取大型对话内容（模型提示和完成、工具输入和输出），并将其作为单独的事件记录发出。**生成的跨度仅包含元数据和小属性。

尽管这种拆分会将完整的对话内容保留在事件记录中，但它会使跨度较小的文档。

```
                          ADOT collection (split)

   Instrumented agent
          |
          |  span with attributes + content
          v
   +--------------------+
   |       ADOT         |  extracts conversation content
   +--------------------+
          |                          |
          | span                     | event record(s)
          | (metadata, attributes)   | (body: input / output messages)
          v                          v
   +--------------------+   +-----------------------+
   |  aws/spans         |   |  event-record         |
   |  log group         |   |  log group            |
   +--------------------+   +-----------------------+
          |                          |
          +-----------+--------------+
                      v
            Evaluation service
       (joins span + event record by traceId / spanId)
```

拆分后，对话内容保存在事件记录中`body`（例如`body.input.messages`和`body.output.messages`），跨度带有用于对其进行分类的标识属性。

## 存储跨度和事件记录的位置
<a name="supported-frameworks-telemetry-location"></a>

**当 ADOT 收集遥测数据时，它会将跨度和事件记录导出到 Amazon CloudWatch，但导出到不同的位置。**
+  **Span** 存储在`aws/spans`日志组中。此日志组是在启用**事务搜索**时创建的，这是评估的先决条件。有关启用事务搜索的详细信息，请参阅[AgentCore 可观察性](observability-telemetry.md)。
+  **事件记录**存储在日志组中，该日志组取决于您的代理托管位置：
  +  **在 Amazon Bedrock Runtime 上： AgentCore 运行**时在日志流中向其`otel-rt-logs`日志组发送事件记录，并为您配置此导出。`/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>`
  +  **托管在 AgentCore 运行时外部**（例如，在亚马逊弹性容器服务 (Amazon ECS)、亚马逊 Elastic Kubernetes Service (Amazon EKS AWS ) 或 Lambda 上）：您的代理将事件记录发送到您通过环境变量配置的日志组。`OTEL_EXPORTER_OTLP_LOGS_HEADERS`

为了评估会话，该服务会从`aws/spans`相应的日志组中读取跨度并将其与其关联的事件记录合并在一起。

## 服务读取内容的位置
<a name="supported-frameworks-telemetry-extraction"></a>

对话内容可以放在不同的地方，具体取决于框架和工具库。评估服务会从存放它的任何位置读取它：
+  **事件记录正文**：当 ADOT 将内容拆分为单独的事件记录（如上所述）时，服务会从与跨度`body`相关的事件记录中读取该记录。
+  **跨度属性**：一些仪器库将跨度上的内容作为属性保留。
+  **内联 span 事件**：一些工具库将内容作为内联事件附加到跨度。

在任何情况下，用于对跨度进行分类的标识属性始终保留在跨度上。这包括将跨度标记为调用代理跨度或执行工具跨度的属性。只有较大的对话内容的位置不同。每个框架的页面列出了每个工具库的标识属性和内容位置。

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

这些 OpenTelemetry 规范描述了 AgentCore 评估所依据的惯例：
+  [跟踪语义惯例](https://opentelemetry.io/docs/specs/semconv/general/trace/)：跨度和轨迹的结构和语义。
+  [事件语义惯例](https://opentelemetry.io/docs/specs/semconv/general/events/)：事件记录的结构和语义。
+  [Generative-AI 语义约定](https://github.com/open-telemetry/semantic-conventions-genai)：用于描述代理、模型和工具操作的`gen_ai.*`属性。