Azure SDK documentation update: Add the span and log record processors for multi-agent GENAI systemsは、マルチエージェント型の生成AIシステムで「どのメインエージェントに紐づく処理か」をトレースとログに持たせやすくする更新です。結論から言うと、すべてのAzure SDK利用者がすぐにコードを変更する必要はありません。主な対象は、Pythonの azure-monitor-opentelemetry を使ってAzure Monitor/Application InsightsへGenAIアプリのテレメトリを送っているチームです。
今回の変更は、Azure SDK for PythonリポジトリのPR #46703で確認できる内容で、azure-monitor-opentelemetry の 1.8.8 (Unreleased) にGenAI main-agent attribution processorを登録する変更が追加されています。PR上ではDraft扱いのため、実運用では「リリース済みパッケージに入ったか」「既存のSpanProcessorやLogRecordProcessorと競合しないか」を確認してから適用するのが安全です。(GitHub)
Azure SDK documentation updateの要点
今回の更新は、Azure SDK for Python内のAzure Monitor OpenTelemetry Distroに関する変更です。PR #46703では、トレース設定時に _GenAIMainAgentSpanProcessor()、ログ設定時に _GenAIMainAgentLogRecordProcessor() を登録する差分が追加されています。どちらも「最初に登録する」コメント付きで追加されており、既存のカスタムプロセッサより前に動かす意図が読み取れます。(GitHub)
| 確認項目 | 内容 |
|---|---|
| 対象パッケージ | azure-monitor-opentelemetry |
| 対象言語 | Python |
| 変更の目的 | マルチエージェントGenAIシステムでメインエージェント情報をspan/logへ伝播しやすくする |
| 主な追加処理 | SpanProcessorとLogRecordProcessorの自動登録 |
| リリース状態 | 1.8.8 (Unreleased) のCHANGELOGに追加 |
| 破壊的変更 | PRチェックリスト上は「breaking changesなし」。ただしDraft/未リリース状態では最終判断しない |
ポイントは、この更新が「新しいAzureサービスの追加」ではなく、GenAIアプリの観測性を高めるためのテレメトリ処理の追加であることです。アプリの業務ロジックを変えるものではありませんが、Azure Monitor上でのトレース分析、ログ検索、障害調査のやり方には影響します。
何が変わるのか
今回のPRでは、CHANGELOG.md に「multi-agent GenAI systemsで microsoft.gen_ai.main_agent.* 属性を自動伝播するため、GenAI main-agent attribution processorsを登録する」という内容が追加されています。さらに _configure.py では、Exporter側からGenAI用のSpanProcessorとLogRecordProcessorをimportし、tracing/loggingのセットアップ時に登録する変更が入っています。(GitHub)
実務的には、次のような変化として理解すると分かりやすいです。
| 観点 | 変更前に起きやすいこと | 変更後に期待されること |
|---|---|---|
| トレース分析 | 子エージェントやツール実行のspanだけを見ると、どの親エージェント起点か分かりにくい | microsoft.gen_ai.main_agent.* 属性により、メインエージェント単位で追跡しやすくなる |
| ログ分析 | ログとspanの関連はあっても、ログ側にメインエージェント情報がない場合がある | 現在のspanからログレコードへメインエージェント属性をコピーしやすくなる |
| 障害調査 | 「どのエージェントが遅いのか」「どの会話で失敗したのか」を横断的に探しにくい | エージェント名、エージェントID、会話IDを軸に調査しやすくなる |
| カスタム処理 | 独自Processorで属性付与・削除をしている場合、順序により結果が変わる | 既存Processorが新しい属性を扱う可能性が出るため、設定確認が必要 |
関連するExporter側のPR #46700では、microsoft.gen_ai.main_agent.name、microsoft.gen_ai.main_agent.id、microsoft.gen_ai.main_agent.version、microsoft.gen_ai.main_agent.conversation_id といった属性のマッピングが追加されています。親spanの microsoft.gen_ai.main_agent.* を子spanへ引き継ぐだけでなく、必要に応じて gen_ai.agent.* や gen_ai.conversation.id からのフォールバックも扱う構成です。(GitHub)
なぜマルチエージェントGenAIで重要なのか
マルチエージェント型のGenAIアプリでは、1つのユーザー依頼が複数の処理に分岐します。たとえば、問い合わせ対応AIであれば、受付エージェント、分類エージェント、検索エージェント、回答生成エージェント、確認エージェントが順番または並列で動くことがあります。
この場合、従来のWebアプリのように「HTTPリクエスト1件＝処理1件」と見なすだけでは不十分です。障害調査では、次のような問いに答える必要があります。
| 調査したいこと | 必要になる情報 |
|---|---|
| 回答品質が落ちた原因はどこか | どのメインエージェント配下で失敗したか |
| レイテンシが急増した原因はどこか | どの子エージェント、ツール、検索処理が遅いか |
| 特定ユーザーの会話だけ失敗したか | conversation IDやthread IDに相当する属性 |
| コスト増の原因はどこか | どのエージェントがモデル呼び出しを増やしているか |
| ログとトレースを突き合わせたい | span属性とlog属性の一貫性 |
OpenTelemetryのGenAI semantic conventionsでも、gen_ai.conversation.id は会話やセッションを相関するための識別子として扱われ、gen_ai.operation.name には invoke_agent などの値が定義されています。アプリ開発者が会話履歴を管理する場合、カスタムのspan/log record processorなどで会話IDをspanやlogに追加できることも説明されています。(OpenTelemetry)
今回のAzure SDK側の変更は、この流れに沿って、Azure Monitorへ送るテレメトリで「メインエージェント帰属」を扱いやすくするものです。
対応すべき人、様子見でよい人
今回の更新は、Azure SDK利用者全員に同じ影響があるわけではありません。特に確認すべきなのは、Azure Monitor OpenTelemetry Distro for Pythonを使い、GenAIアプリのトレースやログを収集しているチームです。
| 利用状況 | 対応優先度 | 理由 |
|---|---|---|
Pythonで azure-monitor-opentelemetry を使い、マルチエージェントGenAIを監視している | 高 | 新しい属性により、トレース・ログ分析の設計が変わる可能性がある |
span_processors や log_record_processors を独自に指定している | 高 | 新しいProcessorが先に登録されるため、属性の上書き・削除・フィルタ処理を確認する必要がある |
| Azure Monitor/Application InsightsでGenAI関連ログをKQL分析している | 中 | customDimensions などに新しい属性が出る可能性がある |
| 単一エージェント、または通常のWeb/API監視だけに使っている | 低 | 直接のメリットは限定的 |
| .NET、Java、Node.jsだけを使っている | 低 | 今回のPRはPythonリポジトリのDistro変更 |
| Azure Monitorを使っていない | 低 | 直接の影響は少ない |
特に注意したいのは、カスタムProcessorを使っているケースです。Microsoft LearnのAPIリファレンスでは、configure_azure_monitor が span_processors と log_record_processors を受け取れることが説明されており、spanやlog recordをエクスポート前に処理できます。今回の変更で組み込みProcessorが追加されると、自社のProcessorが受け取る属性セットが変わる可能性があります。(Microsoft Learn)
まず確認すべき変更ファイル
PR #46703で変更されているファイルは、主に CHANGELOG.md と _configure.py です。ファイル数は少ないものの、影響はAzure Monitor OpenTelemetry Distroの初期化処理に関わります。(GitHub)
| ファイル | 変更内容 | 実務上の確認ポイント |
|---|---|---|
sdk/monitor/azure-monitor-opentelemetry/CHANGELOG.md | 1.8.8 (Unreleased) のFeatures AddedにGenAI main-agent attribution processorsを追加 | リリースノートに正式反映されたか確認する |
azure/monitor/opentelemetry/_configure.py | Exporter側のGenAI Processorをimport | Exporterパッケージ側の対応バージョンが必要になる |
_setup_tracing | _GenAIMainAgentSpanProcessor() を最初に登録 | 独自SpanProcessorとの順序・上書き有無を確認する |
_setup_logging | _GenAIMainAgentLogRecordProcessor() を最初に登録 | 独自LogRecordProcessorやログフィルタとの競合を確認する |
関連PR #46700では「Distro changes – #46703. The exporter needs to be released first.」と説明されており、Distro側だけでなくExporter側のリリース状況も確認すべきです。(GitHub)
移行前に確認するチェックリスト
この更新を取り込む前に、次の順番で確認すると失敗を減らせます。
| 手順 | 確認内容 | 判断基準 |
|---|---|---|
| 依存パッケージを確認 | azure-monitor-opentelemetry と関連Exporterのバージョン | 対象機能が入った正式リリースか |
| リリースノートを確認 | 1.8.8 以降のCHANGELOG | Draft PRではなく、リリース済みの記載か |
| 初期化コードを確認 | configure_azure_monitor() の呼び出し箇所 | 複数回初期化していないか |
| カスタムProcessorを確認 | span_processors、log_record_processors の中身 | 属性の削除、上書き、フィルタがないか |
| ステージングで検証 | 代表的なマルチエージェント処理を実行 | 新属性がspan/logに入るか |
| KQLやダッシュボードを確認 | 既存クエリ、Workbook、アラート | 新属性を活用できるか、既存条件が壊れないか |
なお、PyPI上の azure-monitor-opentelemetry は確認時点で 1.8.7 が最新として表示され、リリース日は2026年3月19日です。今回のPRで触れられている 1.8.8 (Unreleased) の機能を使う前に、実際に対象バージョンが公開されたかを必ず確認してください。(PyPI)
設定確認の基本
PythonでAzure Monitor OpenTelemetry Distroを使う場合、基本的には configure_azure_monitor() を呼び出してApplication Insightsの接続情報を設定します。Microsoft Learnでは、接続文字列を環境変数 APPLICATIONINSIGHTS_CONNECTION_STRING で設定する方法と、configure_azure_monitor に直接渡す方法が示されています。(Microsoft Learn)
import os
from azure.monitor.opentelemetry import configure_azure_monitor
configure_azure_monitor(
connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"],
)既存のカスタムProcessorがある場合は、次のような設定をしている箇所を探します。
from azure.monitor.opentelemetry import configure_azure_monitor
configure_azure_monitor(
connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"],
span_processors=[
# 自社のSpanProcessor
],
log_record_processors=[
# 自社のLogRecordProcessor
],
)今回のPRでは、GenAI main-agent attribution processorがDistro内部で先に登録される差分になっています。したがって、独自Processorでは次の点を確認してください。
| 確認箇所 | 注意点 |
|---|---|
| 属性の削除処理 | microsoft.gen_ai.main_agent.* を不要なカスタム属性として消していないか |
| 属性の上書き処理 | gen_ai.agent.* や gen_ai.conversation.id を別の値で上書きしていないか |
| ログ整形処理 | log recordのattributesを再作成して、新属性を落としていないか |
| サンプリング処理 | メインエージェント単位の分析に必要なspanを落としすぎていないか |
| PII対策 | GenAI関連属性やログに機密情報が混ざっていないか |
Azure Monitorで確認するKQL例
リリース後に検証する場合は、まずAzure Monitor LogsやApplication Insightsで新しい属性が入っているかを確認します。実際のテーブル名や格納先は構成によって異なるため、以下は調査の出発点として使ってください。
traces
| where timestamp > ago(24h)
| extend main_agent_name = tostring(customDimensions["microsoft.gen_ai.main_agent.name"])
| extend main_agent_id = tostring(customDimensions["microsoft.gen_ai.main_agent.id"])
| extend conversation_id = tostring(customDimensions["microsoft.gen_ai.main_agent.conversation_id"])
| where isnotempty(main_agent_name) or isnotempty(conversation_id)
| summarize count() by main_agent_name, main_agent_id
| order by count_ desc依存関係やリクエスト側も確認したい場合は、dependencies や requests を対象に同じ属性を探します。
dependencies
| where timestamp > ago(24h)
| extend main_agent_name = tostring(customDimensions["microsoft.gen_ai.main_agent.name"])
| where isnotempty(main_agent_name)
| summarize avg_duration_ms = avg(duration), count() by main_agent_name, target
| order by avg_duration_ms descログ側でメインエージェント単位のエラーを見たい場合は、次のように確認します。
traces
| where timestamp > ago(24h)
| where severityLevel >= 3
| extend main_agent_name = tostring(customDimensions["microsoft.gen_ai.main_agent.name"])
| extend conversation_id = tostring(customDimensions["microsoft.gen_ai.main_agent.conversation_id"])
| summarize error_count = count() by main_agent_name, conversation_id
| order by error_count descこの検証で属性が見つからない場合は、単に更新が効いていないとは限りません。アプリ側や利用しているGenAIフレームワークが、そもそも gen_ai.agent.name、gen_ai.agent.id、gen_ai.conversation.id などの元になる属性を出していない可能性があります。
よくある失敗パターン
Draft PRをリリース済み機能として扱う
今回のPR #46703は、確認時点でDraftとして表示されています。CHANGELOGに Unreleased として記載されている段階では、本番環境の更新判断をしない方が安全です。正式リリース後に、PyPI、GitHubのrelease notes、依存関係のバージョンを確認してから取り込みましょう。(GitHub)
Exporter側の対応を見落とす
Distro側のPRは、Exporter側から _GenAIMainAgentSpanProcessor と _GenAIMainAgentLogRecordProcessor をimportしています。関連PR #46700ではExporter側にProcessor実装が追加されているため、Distroだけを見て判断すると依存関係を見落とす可能性があります。(GitHub)
内部クラスを直接importして使う
今回のProcessor名は _GenAIMainAgentSpanProcessor のようにアンダースコアで始まっています。Pythonでは慣例的に内部実装を示す名前です。PRの意図はDistroの設定処理で自動登録することなので、公式ドキュメントで案内されるまでは、アプリコードから直接importして使う設計は避けるのが無難です。
既存のログ整形で属性を落とす
ログレコードを独自に整形している場合、attributes を作り直す処理によって新しい microsoft.gen_ai.main_agent.* が消えることがあります。特に、ログ出力前に「許可リスト方式」で属性を残している場合は、許可リストに新属性を追加する必要があります。
機密情報対策を後回しにする
今回の変更自体は主にメインエージェント属性の伝播ですが、GenAIのテレメトリ全体では入力メッセージ、出力メッセージ、システム指示などが扱われる場合があります。OpenTelemetryのGenAI仕様でも、入力・出力メッセージやsystem instructionsには機密情報が含まれる可能性があると注意されています。GenAI監視を強化する際は、プロンプト、回答、会話ID、ユーザーIDの扱いを同時に見直してください。(OpenTelemetry)
実務での活用シーン
この更新が入ると、マルチエージェントGenAIの運用では次のような分析がしやすくなります。
| 活用シーン | 使い方 |
|---|---|
| 障害調査 | エラーlogを main_agent.name で集計し、失敗しやすいエージェントを特定する |
| 性能分析 | main_agent.name と依存関係のdurationを組み合わせ、遅い処理を見つける |
| 品質改善 | conversation ID単位で失敗パターンを追跡し、プロンプトやツール選択を改善する |
| コスト管理 | メインエージェント単位でモデル呼び出しの増加傾向を分析する |
| リリース検証 | 新バージョンのエージェントが旧バージョンより遅くなっていないか確認する |
特に効果が大きいのは、複数のエージェントが同じモデルや同じ検索基盤を共有しているケースです。単純な依存関係グラフだけでは「どの上位エージェントの文脈で遅くなったか」が見えにくいため、メインエージェント属性を分析軸に加える価値があります。
本番適用時の判断基準
正式リリース後に取り込む場合でも、すぐに全環境へ展開するのではなく、段階的に検証するのがおすすめです。
| 判断項目 | 本番適用してよい目安 |
|---|---|
| パッケージ状態 | PyPIまたは公式リリースノートで対象バージョンが公開済み |
| 依存関係 | DistroとExporterの対応バージョンがそろっている |
| 既存Processor | 新属性を消したり上書きしたりしないことを確認済み |
| テレメトリ量 | 新属性追加によるログ量・課金影響を確認済み |
| セキュリティ | 会話IDやエージェントIDの扱いが社内ルールに合っている |
| 運用監視 | KQL、Workbook、アラートが新属性に対応済み |
判断に迷う場合は、まずステージング環境で代表的な会話フローを実行し、spanとlogに microsoft.gen_ai.main_agent.* が入るかを確認してください。値が入らない場合は、Azure SDK側ではなく、アプリやGenAIフレームワーク側で元になる gen_ai.* 属性が不足している可能性があります。
次に取るべき行動
今回のAzure SDK documentation updateは、マルチエージェントGenAIシステムの可観測性を高めるための重要な下準備です。ただし、確認時点では 1.8.8 (Unreleased) に向けたPR段階の情報であり、正式リリース済み機能として扱うべきではありません。
まずは、自社アプリが azure-monitor-opentelemetry を使っているか、configure_azure_monitor() に独自の span_processors や log_record_processors を渡しているかを確認してください。そのうえで、正式リリース後にステージング環境で新属性の出力、既存KQLへの影響、機密情報の扱いを検証します。
マルチエージェントGenAIを本番運用しているチームにとって、次に見るべきポイントは「パッケージを上げるか」だけではありません。どのエージェントを分析軸にするか、どの会話IDを安全に保持するか、どのログを残しどの情報を落とすかまで含めて、監視設計を見直すタイミングと考えるべきです。
コメント