View a markdown version of this page

スパン、イベントレコード、テレメトリシグナル - Amazon Bedrock AgentCore
ADOT がテレメトリを分割する方法スパンとイベントレコードが保存される場所サービスがコンテンツを読み取る場所リファレンス

スパン、イベントレコード、テレメトリシグナル

Amazon Bedrock AgentCore Evaluations は、エージェントの動作を理解するために 2 つのテレメトリシグナルを処理します。

  • スパンは個々のオペレーションを記述します。スパンには、オペレーションの名前、スコープ、タイムスタンプ、属性に関するメタデータが格納されます。スパンには会話コンテンツが含まれる場合や、そのコンテンツが別のイベントレコードに存在する場合もあります。

  • イベントレコードには、モデル、ツール、エージェントの入力と出力のbodyフィールドにペイロードコンテンツが格納されます。イベントレコードは、共有 traceIdおよび によってそのスパンと関連付けられますspanId。イベントレコードは OpenTelemetry イベント規則に従います。詳細については、「 リファレンス」を参照してください。

セッションを評価するには、サービスにスパンと、該当する場合は相関イベントレコードの両方が必要です。スパンごとに、サービスは以下を実行します。

  1. フレームワーク固有の属性からスパンのタイプを識別します。詳細については、フレームワークごとのページを参照してください。

  2. ユーザープロンプト、エージェントのレスポンス、ツールの入力と出力など、必要な値を読み取ります。これらの値は、スパンの属性または相関イベントレコードから取得されます。

トピック

ADOT がテレメトリを分割する方法

エージェントが 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) に存在し、スパンには分類に使用される識別属性が保持されます。

スパンとイベントレコードが保存される場所

ADOT がテレメトリを収集すると、スパンとイベントレコードを Amazon CloudWatch にエクスポートしますが、場所は異なります。

  • スパンはaws/spansロググループに保存されます。このロググループは、評価の前提条件であるトランザクション検索が有効になっている場合に作成されます。トランザクション検索の有効化の詳細については、AgentCore Observability」を参照してください。

  • イベントレコードは、エージェントがホストされている場所に依存するロググループに保存されます。

    • 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、適切なロググループからの相関イベントレコードに結合します。

サービスがコンテンツを読み取る場所

会話コンテンツは、フレームワークと計測ライブラリに応じて、さまざまな場所に住むことができます。評価サービスは、それを保持する場所から読み取ります。

  • イベントレコード本文: ADOT がコンテンツを別のイベントレコード (上記) に分割すると、サービスはスパンにbody相関するイベントレコードから読み取ります。

  • スパン属性: 一部の計測ライブラリは、コンテンツをスパンに属性として保持します。

  • インラインスパンイベント: 一部の計測ライブラリはコンテンツをインラインイベントとしてスパンにアタッチします。

スパンの分類に使用される識別属性は、いずれの場合も常にスパンに残ります。これには、スパンを呼び出しエージェントスパンまたは実行ツールスパンとしてマークする 属性が含まれます。大きな会話コンテンツの場所のみが異なります。フレームワークごとのページには、各計測ライブラリの識別属性とコンテンツの場所の両方が一覧表示されます。

リファレンス

これらの OpenTelemetry 仕様では、AgentCore Evaluations が構築する規則について説明します。