次の方法で共有

Microsoft Agent Framework ワークフロー - 可観測性

可観測性は、実行中のワークフローの内部状態と動作に関する分析情報を提供します。 これには、ワークフローの監視とデバッグに役立つログ記録、メトリック、トレース機能が含まれます。

ヒント

可観測性はフレームワーク全体の機能であり、ワークフローに限定されません。 詳細については、「 可観測性」を参照してください。

標準の GenAI テレメトリとは別に、Agent Framework ワークフローは追加のスパン、ログ、メトリックを出力して、ワークフローの実行に関するより深い分析情報を提供します。 これらの可観測機能は、開発者がメッセージのフロー、Executor のパフォーマンス、発生する可能性のあるエラーを理解するのに役立ちます。

可観測性を有効にする

アプリケーションで 可観測性を有効にする手順については、「可観測性 の有効化」を参照してください。

アプリケーションで 可観測性を有効にする手順については、「可観測性 の有効化」を参照してください。

ワークフローの範囲

ワークフローの実行中に、次のスパンが生成されます。

スパン名 Description
workflow.build ワークフロー ビルドごとに出力されます。
workflow.session ワークフロー実行の有効期間全体を表す外側のスパン (開始から停止またはエラーまで)。
workflow_invoke ワークフロー セッション内の各入力から停止までのサイクルに対して出力されます。
executor.process {executor_id} メッセージを処理する各 Executor に対して出力されます。 Executor ID がスパン名に追加されます。
edge_group.process メッセージを処理するエッジ グループごとに出力されます。
message.send Executor から別の Executor に送信される各メッセージに対して出力されます。

ワークフローの実行中に、次のスパンが生成されます。

スパン名 Description
workflow.build ワークフロー ビルドごとに出力されます。
workflow.run ワークフローの実行ごとに出力されます。
executor.process {executor_id} メッセージを処理する各 Executor に対して出力されます。 Executor ID がスパン名に追加されます。
edge_group.process {edge_group_type} メッセージを処理するエッジ グループごとに出力されます。 エッジ グループの種類がスパン名に追加されます。
message.send Executor から別の Executor に送信される各メッセージに対して出力されます。

スパン属性

スパンには、操作に関する追加のコンテキストを提供する属性が含まれます。 ワークフロー スパンでは、次の属性が設定されます。

特性 スパン Description
workflow.id workflow.build、workflow.session ワークフローの一意識別子。
workflow.name workflow.session ワークフローの名前です。
workflow.description workflow.session ワークフローの説明。
workflow.definition workflow.build ワークフロー グラフの JSON 定義。
session.id workflow.session 一意のセッション識別子。
executor.id executor.process 実行者の一意識別子。
executor.type executor.process Executorの型名が表示されます。
executor.input executor.process 入力メッセージ。 機密データが有効になっている場合にのみ設定します。
executor.output executor.process Executor の出力。 機密データが有効になっている場合にのみ設定します。
message.type executor.process、message.send メッセージの型名。
message.content message.send メッセージの内容。 機密データが有効になっている場合にのみ設定します。
message.source_id message.send メッセージを送信した Executor の ID。
message.target_id message.send ターゲット Executor の ID (指定されている場合)。
edge_group.type edge_group.process エッジ グループの種類。
edge_group.delivered edge_group.process メッセージが配信されたかどうか (ブール型)。
edge_group.delivery_status edge_group.process 配信結果 ( エッジ グループの配信状態を参照)。
error.type エラー時の範囲 例外タイプの名称
特性 スパン（範囲） Description
workflow.id workflow.build、workflow.run ワークフローの一意識別子。
workflow.name workflow.run ワークフローの名前です。
workflow.description workflow.run ワークフローの説明。
workflow.definition workflow.build ワークフロー グラフの JSON 定義。
workflow_builder.name workflow.build ワークフロー ビルダーの名前。
workflow_builder.description workflow.build ワークフロー ビルダーの説明。
executor.id executor.process Executor の一意識別子。
executor.type executor.process 実行者の型名。
message.type executor.process、message.send メッセージのタイプ名。
message.payload_type executor.process メッセージ ペイロードのデータ型。
message.destination_executor_id message.send ターゲット Executor の ID (指定されている場合)。
message.source_id edge_group.process メッセージを送信した Executor の ID。
message.target_id edge_group.process ターゲット Executor の ID (指定されている場合)。
edge_group.type edge_group.process エッジ グループの種類。
edge_group.id edge_group.process エッジ グループのユニークな識別子。
edge_group.delivered edge_group.process メッセージが配信されたかどうか (ブール型)。
edge_group.delivery_status edge_group.process 配信結果 ( エッジ グループの配信状態を参照)。

Span イベント

スパン イベントは、スパンにアタッチされた構造化されたログ エントリであり、各スパン内の重要な瞬間のタイムラインを提供します。

イベント名 スパン Description
build.started workflow.build ビルド プロセスの開始時に出力されます。
build.validation_completed workflow.build ビルド検証に合格したときに出力されます。
build.completed workflow.build ビルドが正常に完了したときに出力されます。
build.error workflow.build ビルドが失敗したときに出力されます。
session.started workflow.session ワークフロー セッションの開始時に生成されます。
session.completed workflow.session ワークフロー セッションが完了したときに生成されます。
session.error workflow.session ワークフロー セッションでエラーが発生したときに生成されます。
workflow.started workflow_invoke ワークフロー呼び出しの開始時に生成されます。
workflow.completed workflow_invoke ワークフロー呼び出しが完了したときに生成されます。
workflow.error workflow_invoke ワークフロー呼び出しでエラーが発生したときに生成されます。
イベント名 スパン Description
build.started workflow.build ビルド プロセスの開始時に出力されます。
build.validation_completed workflow.build ビルド検証に合格したときに出力されます。
build.completed workflow.build ビルドが正常に完了したときに出力されます。
build.error workflow.build ビルドが失敗したときに出力されます。
workflow.started workflow.run ワークフロー実行の開始時に生成されます。
workflow.completed workflow.run ワークフローの実行が完了したときに生成されます。
workflow.error workflow.run ワークフロー実行でエラーが発生したときに生成されます。

Executor が別の Executor にメッセージを送信すると、 message.send スパンが executor.process スパンの子として作成されます。 ただし、ターゲット Executor のexecutor.processスパンは、実行が入れ子になっていないため、message.sendスパンの子ではありません。 代わりに、ターゲット Executor のexecutor.processスパンは、ソース Executor のスパンにmessage.send。 このリンクにより、入れ子になった呼び出し階層を意味することなく、ワークフロー実行を通じてトレース可能なパスが作成されます。

同じリンク方法は、因果関係の追跡のためにソース edge_group.process スパンにリンクされているmessage.sendスパンにも適用されます。 これは、複数のソース スパンが 1 つの処理スパンに寄与するファンイン シナリオをサポートします。

Edge グループの配信状態

エッジ グループの処理範囲には、各エッジ グループを介したメッセージ ルーティングの結果を示す配信状態属性が含まれます。 edge_group.delivery_status属性は、次のいずれかの値に設定されます。

地位 Description
delivered メッセージはターゲット Executor に配信されました。
dropped type mismatch ターゲット Executor は、メッセージの種類を処理できません。
dropped target mismatch メッセージで、このエッジと一致しないターゲットが指定されました。
dropped condition false エッジ ルーティング条件が false に評価されました。
exception エッジ処理中に例外が発生しました。
buffered メッセージはバッファーに格納され、追加のメッセージ (ファンイン) を待機しています。

edge_group.deliveredブール値属性を使用すると、メッセージが正常に配信されたかどうかを簡単に確認できます。

テレメトリの構成

ワークフロー テレメトリは、ワークフロー ビルダーの WithOpenTelemetry 拡張メソッドを使用して有効にすることができます。 WorkflowTelemetryOptions クラスでは、出力されるスパンをきめ細かく制御できます。

オプション デフォルト Description
EnableSensitiveData false スパン属性には、生の入力、出力、およびメッセージの内容が含まれます。
DisableWorkflowBuild false workflow.buildスパンを無効にします。
DisableWorkflowRun false workflow.sessionとworkflow_invokeのスパンを無効にします。
DisableExecutorProcess false executor.processスパンを無効化します。
DisableEdgeGroupProcess false edge_group.processスパンを無効にします。
DisableMessageSend false message.send のスパンを無効化します。

Warnung

機密データを有効にすると、生のメッセージ コンテンツ、Executor 入力、および Executor 出力がテレメトリに含まれます。 これは、テレメトリ データが適切に保護されているセキュリティで保護された環境でのみ有効にします。

ワークフロー テレメトリは、グローバル enable_instrumentation() 関数によって有効になります。 インストルメンテーションを有効にすると、すべてのワークフロー スパンが自動的に出力されます。 configure_otel_providers()関数を使用して、トレース、メトリック、ログのエクスポーターを設定できます。

Warnung

トレースをエクスポートするときに機密データが適切に保護されていることを確認するには、テレメトリ パイプラインの構成を確認します。

次のステップ

  • Last updated on