# 跨度、事件記錄和遙測訊號
<a name="supported-frameworks-telemetry"></a>

Amazon Bedrock AgentCore Evaluations 會處理兩個遙測訊號，以了解代理程式的行為：
+  **範圍**描述個別操作。跨度會攜帶有關 操作的中繼資料：其名稱、範圍、時間戳記和屬性。範圍也可能帶有對話內容，或者該內容可能存在於單獨的事件記錄中。
+  **事件記錄**在`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 Distro for 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，但匯出到**不同的**位置。
+  **跨度**會存放在`aws/spans`日誌群組中。此日誌群組會在啟用**交易搜尋**時建立，這是評估的先決條件。如需啟用交易搜尋的詳細資訊，請參閱 [AgentCore 可觀測性](observability-telemetry.md)。
+  **事件記錄**存放在日誌群組中，取決於您的代理程式託管的位置：
  +  **在 Amazon Bedrock AgentCore 執行期**：執行期會在日誌串流`/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>`中向其`otel-rt-logs`日誌群組 發出事件記錄，並為您設定此匯出。
  +  在** AgentCore 執行期 （例如，在 Amazon Elastic Container Service (Amazon ECS)、Amazon Elastic Kubernetes Service (Amazon EKS) 或 Lambda 上） 之外託管**：您的代理程式會向透過`OTEL_EXPORTER_OTLP_LOGS_HEADERS`環境變數設定的日誌群組發出事件記錄。 AWS 

若要評估工作階段，服務會從 進行讀取`aws/spans`，並將其與來自適當日誌群組的關聯事件記錄聯結。

## 服務讀取內容的位置
<a name="supported-frameworks-telemetry-extraction"></a>

視架構和檢測程式庫而定，對話內容可以存在於不同的位置。評估服務會從任何位置進行讀取：
+  **事件記錄內文**：當 ADOT 將內容分割成單獨的事件記錄 （如上所述） 時，服務會從與跨度`body`相關的事件記錄中讀取內容。
+  **範圍屬性**：某些檢測程式庫會將範圍上的內容保留為屬性。
+  **內嵌跨度事件**：某些檢測程式庫會將內容連接至跨度，做為內嵌事件。

用於分類跨度的識別屬性一律會保留在跨度上。這包括將範圍標記為叫用代理程式範圍或執行工具範圍的屬性。只有較大的對話內容的位置會有所不同。每個影格頁面會列出每個檢測程式庫的識別屬性和內容位置。

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

這些 OpenTelemetry 規格說明 AgentCore Evaluations 建置的慣例：
+  [追蹤語意慣例](https://opentelemetry.io/docs/specs/semconv/general/trace/)：跨和追蹤的結構和語意。
+  [事件語意慣例](https://opentelemetry.io/docs/specs/semconv/general/events/)：事件記錄的結構和語意。
+  [生成式 AI 語意慣例](https://github.com/open-telemetry/semantic-conventions-genai)：用於描述代理程式、模型和工具操作的`gen_ai.*`屬性。