Microsoft Foundry でトレースを設定する

重要

この記事でマークされている項目 (プレビュー) は、現在パブリック プレビュー段階です。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境のワークロードにはお勧めしません。 特定の機能がサポートされていないか、機能が制限されている可能性があります。 詳細については、「Microsoft Azure プレビューの使用条件を参照してください。

メモ

トレースは、プロンプト エージェントとホステッド エージェントで一般提供されています。 ワークフローエージェントと外部エージェントはプレビュー段階です。

トレースを使用して AI エージェントをデバッグし、運用環境での動作を監視します。 トレースでは、待機時間、例外、プロンプト コンテンツ、取得操作など、詳細なテレメトリがキャプチャされるため、問題をより迅速に特定して修正できます。

推奨される開始点は、 サーバー側のトレースです。 Foundry では、Application Insights リソースをプロジェクトに接続した後に自動的に有効になります。 コードの変更は必要なく、トレースは有効にしてから数分以内に使用できます。 サーバー側トレースは、Foundry でホストされている任意のエージェントに対して機能します。 エージェント呼び出しを囲むカスタム ロジックをトレースするなど、独自のアプリケーション コードを可視化する必要がある場合は、2 番目の手順としてクライアント側のインストルメンテーションを追加できます。

Microsoft Foundry スキルは、サーバー側またはクライアント側のトレースを選択し、不足しているテレメトリのトラブルシューティングに役立ちます。

前提 条件

Application Insights を Foundry プロジェクトに接続する

Foundry は、OpenTelemetry セマンティック規則を使用して Application Insights にトレースを格納します。

  1. Microsoft Foundry にサインイン>。 新しいファウンドリーのトグルがオンになっていることを確認します。 これらの手順は Foundry (新規) を参照します。

  2. Foundry プロジェクトを開きます。

  3. 左側のナビゲーションで、[エージェント] を選択 します。

  4. 上部にある [トレース] を選択 します。

  5. 右側の [ 接続 ] を選択して、Application Insights リソースを作成または接続します。

    トレースと接続ボタンを示す [エージェント] タブのスクリーンショット。

  • 既存のリソースを接続するには、リソースを選択し、[ 接続] を選択します。
  • 新しいリソースを作成するには、[ 新規作成] を選択してウィザードを完了します。

接続が成功すると、確認メッセージが表示されます。

プロジェクトの詳細接続パスを使用する

メッセージ バーまたは [接続] ボタンが表示されない場合は、この代替方法を使用して Application Insights Azure Monitor有効にします。

  1. 右上のナビゲーションで [管理] を選択し、Project詳細を選択します。 [Projectの詳細] オプションが強調表示されている [管理] セクションのスクリーンショット。
  2. [ 接続済みリソース ] タブを選択し、[ 接続の追加] を選択します。 [接続されているリソース] タブが選択され、[接続の追加] ボタンが強調表示されているProjectの詳細のスクリーンショット。
  3. [ 接続の選択] で、[ Application Insights] を選択します。 Application Insights が強調表示された [接続の選択] のスクリーンショット。

Microsoft Entra 認証を使用したトレース インジェストについては、「Foundry Agent トレース インジェスト用に Microsoft Entra 認証を構成する (プレビュー)」を参照してください。

リソースを接続すると、プロジェクトでトレースを使用する準備が整います。

重要

テレメトリのクエリに必要なアクセス許可があることを確認します。

AI エージェントの実装

エージェントの構築と実行方法に合ったアプローチを選択します。

Foundry ポータルのサーバー側トレース

サーバー側トレースから始めます。 Foundry は、コードを変更せずに、一般的なエージェントとワークフローのシナリオのトレースをログに記録します。

  • Foundry は、Foundry ポータルで、プロンプト エージェント、ホスト エージェント、およびワークフローのサーバー側トレースを自動的にログに記録します。 Foundry プロジェクトでトレースを有効にすると、過去90日分の標準で利用できるトレースにアクセスできます。
  • Foundry では、上位のエージェント フレームワークとの簡単な 統合 もサポートされています。

Microsoft Foundry SDK を使用したクライアント側トレース (Python)

次の手順を使用して、OpenTelemetry と Azure SDK トレース プラグインをインストールします。

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

リファレンス: azure-ai-projects、 azure-core-tracing-opentelemetry

重要

アプリケーションでプロジェクトのエンドポイントを使用するには、Microsoft Entra IDを構成する必要があります。 Microsoft Entra IDを構成しない場合は、Application Insights 接続文字列を使用します。

エージェントを実行した後、 Foundry ポータルでトレースを表示および分析できます。

詳細な手順と SDK 固有のコード例については、azure-ai-projects (Python SDK) のトレーシングおよび エージェント用の Telemetry サンプルを参照してください。

Microsoft Foundry Toolkit for Visual Studio Code拡張機能を使用してローカルでトレースする

Microsoft Foundry Toolkit for Visual Studio Code拡張機能を使用すると、ローカル OTLP 互換コレクターを使用して VS Code でローカルにトレースできます。 このアプローチは、開発とデバッグに最適です。

このツールキットは、Foundry Agent Service、OpenAI、Anthropic、LangChain などの AI フレームワークを OpenTelemetry 経由でサポートします。 クラウド アクセスを必要とせずに、VS Code でトレースをすぐに確認できます。

詳細なセットアップ手順と SDK 固有のコード例については、「 Foundry Toolkit のトレース」を参照してください。

トレースの表示と分析

Foundry ポータルでトレースを表示する

Foundry プロジェクトで、エージェントまたはワークフローの [ トレース ] タブに移動します。 過去 90 日間の取り込まれたトレースを検索、フィルター処理、または並べ替えることができます。

トレースを選択して各スパンを順に確認し、問題を特定し、アプリケーションの応答を確認します。 このプロセスは、アプリケーションの問題をデバッグして特定するのに役立ちます。

Azure Monitorでトレースを表示する

トレースは Azure Monitor Application Insights に送信されるため、そこでトレースを表示できます。

トレースをAzure Monitorに送信し、Azure Monitor リソースを作成する方法の詳細については、Azure Monitor OpenTelemetry のドキュメントを参照してください。

会話の結果を表示する

会話は、ユーザーとエージェントの間のエンド ツー エンドのダイアログ履歴の永続的なコンテキストです。 Foundry ポータルの [トレース] ページでは、エージェント実行の会話結果とトレースをすぐに確認できます。

レスポンス ID またはこの会話に対応するトレース ID を使用して検索します。 次に、確認する 会話 ID を 選択します。

  • 会話履歴の詳細
  • 実行時の応答情報とトークン
  • 順序付けされたアクション、実行ステップ、およびツール呼び出し
  • ユーザーとエージェントの間の入力と出力

トレース タイムラインと実行手順の詳細を含む会話 ID を示す Foundry の [会話の詳細] ウィンドウのスクリーンショット。

トレースが機能することを確認する

  1. プロジェクトが Application Insights に接続されていることを確認します。 必要に応じて、「 Application Insights を Foundry プロジェクトに接続する」の手順に従います。

  2. エージェントまたはワークフローを少なくとも 1 回実行します (たとえば、ポータルやアプリを使用)。

  3. Foundry プロジェクトで、[ トレース ] ビューを開き、新しいトレースが表示されたことを確認します。

    トレースが正常に動作すると、タイムスタンプ、期間、状態インジケーターを含む最近のトレースの一覧が表示されます。 トレースを選択すると、そのスパンの詳細が表示されます。

新しいトレースが表示されない場合は、数分待ってから更新し、「 トラブルシューティング」を参照してください。

セキュリティとプライバシー

トレースでは、ユーザー入力、モデル出力、ツールの引数や結果などの機密情報をキャプチャできます。 リスクを軽減するには、次のプラクティスを使用します。

  • シークレット、資格情報、またはトークンは、プロンプト、ツール引数、またはスパン属性に格納しないでください。
  • テレメトリに表示される前に、個人データやその他の機密コンテンツを編集または最小化します。
  • トレース データを運用テレメトリとして扱い、ログとメトリックに使用するのと同じアクセス制御と保持ポリシーを適用します。

詳細なガイダンスについては、 セキュリティとプライバシーに関するページを参照してください。

データの保持とコスト

Foundry は、プロジェクトに接続されている Application Insights リソースにトレースを格納します。 データの保持と課金は、Application Insights とLog Analytics構成に従います。

トラブルシューティング

問題 原因 解決方法
Foundry ポータルにトレースが表示されない トレースが接続されていない、最近のトラフィックがない、またはインジェストが遅れている Application Insights 接続を確認し、新しいエージェント トラフィックを生成し、数分後に更新します。
テレメトリのクエリまたは表示時に承認エラーが表示される Application Insights または Log Analytics に対する RBAC アクセス許可がありません 接続されているリソースの アクセス制御 (IAM) でアクセスを確認します。 ログ クエリの場合は、Log Analytics 閲覧者ロールを割り当てます。 テーブルが 保護されている場合は、 Privileged Monitoring Data Reader も割り当てます。
クライアント側トレースが表示されない インストルメンテーションがインストールまたは構成されていない パッケージのインストールを再確認し、Microsoft Foundry SDK (Python) を使用して、Client 側トレースにリンクされている SDK ガイダンスに従います。
機密性の高いコンテンツがトレースに表示される プロンプト、ツール引数、または出力に機密データが含まれている テレメトリに入る前に機密データを編集し、 セキュリティとプライバシーのガイダンスに従います。

関連コンテンツ

トレースを設定したら、これらのリソースを調べて理解を深め、監視機能を拡張します。

  • Last updated on