# スパン、イベントレコード、テレメトリシグナル
<a name="supported-frameworks-telemetry"></a>

Amazon Bedrock AgentCore Evaluations は、エージェントの動作を理解するために 2 つのテレメトリシグナルを処理します。
+  **スパンは**個々のオペレーションを記述します。スパンには、オペレーションの名前、スコープ、タイムスタンプ、属性に関するメタデータが格納されます。スパンには会話コンテンツが含まれる場合や、そのコンテンツが別のイベントレコードに存在する場合もあります。
+  **イベントレコード**には、モデル、ツール、エージェントの入力と出力の`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](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)、 AWS Lambda など): エージェントは、 `OTEL_EXPORTER_OTLP_LOGS_HEADERS`環境変数を使用して設定したロググループにイベントレコードを出力します。

セッションを評価するために、サービスは からスパンを読み取り`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/): イベントレコードの構造とセマンティクス。
+  [Generative-AI セマンティック規則](https://github.com/open-telemetry/semantic-conventions-genai): エージェント、モデル、ツールのオペレーションを記述するために使用される`gen_ai.*`属性。