Application Insightsを用いた環境レベルのテレメトリ(プレビュー)

[この記事はプレリリース ドキュメントであり、変更されることがあります。]

Azure アプリケーション Insightsを使って、管理環境からエクスポートされたCopilot Studioエージェントのトレースを監視してください。 エクスポートの設定後は、Azure MonitorとApplication Insightsを使ってエージェントの実行を検証し、ノードやツールの実行を監視し、アラートを作成し、運用分析用のカスタムクエリやダッシュボードを構築しましょう。

この記事では、Power Platform管理センターを通じてCopilot StudioエージェントのトレースをAzure アプリケーション Insightsに環境レベルでエクスポートする方法を説明しています。

Prerequisites

データエクスポート接続を設定する前に、「 Application Insightsへのデータエクスポート」の前提条件を満たしてください。

エクスポートされる内容

エクスポートを有効にすると、Copilot Studioエージェントのトレーステレメトリは、調査、ダッシュボード、アラートをサポートするトレース指向のOpenTelemetryに準拠した観測可能性形式でApplication Insightsに書き込みます。

Copilot Studio のエージェント イベントは、dependencies テーブルにスパンとして記録されます。 各エクスポートされたイベント(InvokeAgent、 ExecuteTool、 OutputMessages)は単一のスパン行(itemType = dependency)です。

スパンがどのようにしてトレースを形成するか

テレメトリはOpenTelemetryのトレース&スパンモデルに従い、 および 列を通じて再構成されています。

• 各エージェントターンは独立した トレースであり、共有 operation_Id で識別されるため、Application Insightsはターンをグループ化し、エンドツーエンドのトランザクションビューでレンダリングできます。
• InvokeAgent スパンは、そのターンのトレースの ルート です。 その ExecuteTool と、それに接続された OutputMessages のスパンがその下に重なり合っており、それぞれが operation_ParentId＝ InvokeAgent のスパンの id を保持しています。
• 会話は 複数のターンにまたがり、それぞれが別々の痕跡として発せられる。 gen_ai.conversation.idごとにグループ化やフィルターをかけて、会話の展開を再びつなげてください。
• OutputMessages スパンは必ずしも InvokeAgent ルートを生成するとは限らないため、（設計上）対応する親がないまま到着し、独立した単一ノードのトレースとして表示されることがあります。

エクスポート パッケージの作成

エクスポートタイプをCopilot Studioに設定したエクスポートパッケージを作成し、Power Platform管理センターのドキュメントの「Create a export package」の指示に従って作成してください。

構成を検証する

エクスポート設定を保存した後、エージェントとテスト会話を行い、テレメトリがApplication Insightsに届くか確認してください。 新しい構成ではテレメトリの配達には最大24時間かかることがあります。 次の点を検証します。

• エージェント スパンは dependencies テーブルに表示されます。
• 各ターンにおける InvokeAgent、ExecuteTool、OutputMessages のスパンは、operation_Id を共有します。

Application Insights フィールド

以下の表は dependencies 表のフィールドと、3つのエクスポートされたエージェントイベントそれぞれ( InvokeAgent、 ExecuteTool、 OutputMessages)ごとに入力されているフィールドを示しています。 エージェントおよびオペレーションの意味論は、ネイティブカラムではなく、 customDimensions ( gen_ai.* キー、例えば gen_ai.operation.name)に含まれます。

customDimensions プロパティ

すべてのスパンには customDimensions JSONが含まれています。 以下の表は、すべてのスパンに共通する鍵を示しています。

イベント固有のキー

以下の表はイベント固有のキーを示しています:

現在のスキーマを発見する

この記事で記録されているスキーマは時間とともに進化する可能性があります。 先に述べたテーブルだけに頼るのではなく、以下のクエリを使って自分の環境で最新のスキーマを検証してください。

ネイティブ テーブルの列を一覧表示する

次のクエリは dependencies テーブルのカラムレベルのスキーマを返します。 クエリ、ダッシュボード、アラートを作成する際に利用可能なネイティブカラムを確認するために使います。

dependencies
| getschema
| project ColumnName, ColumnType
| order by ColumnName asc

customDimensions キー (動的プロパティ) を確認する

以下のクエリは、customDimensionsテーブル内のdependencies JSON内のすべてのキーを一覧にします。プロパティ名、どのエージェントイベント(InvokeAgent、ExecuteTool、OutputMessages)、そしてサンプル値です。 ネイティブのカラムスキーマとは異なり、これらのプロパティは動的であるため、SDKが新しい gen_ai.* や他のキーを追加してもこのクエリは正確さを保ちます。 利用可能な属性の真実のライブソースとして活用しましょう。

dependencies
| where timestamp > ago(7d)
| mv-expand Key = bag_keys(customDimensions) to typeof(string)
| summarize Events = make_set(name), SampleValue = take_any(tostring(customDimensions[Key])) by Key
| order by Key asc

エクスポートされたテレメトリをモニターします

Application Insights Logs を使ってエージェントの活動を照会し、エージェントやツールの実行を調査してください。 エクスポートされたすべてのテレメトリは、 dependencies テーブルにスパンとして格納されます:

• 各エージェントのターンは1つのトレースであり、共通の operation_Id によってグループ化されます。
• InvokeAgent スパンはトレースのルートであり、ExecuteTool および OutputMessages スパンは、operation_ParentId 至るまでその下にネストされています。
• gen_ai.conversation.idごとにグループ化して同じ会話の複数ターンをスレッドし、そのIDを_分割してサブエージェントのトレースも含めます。

エージェント(プレビュー)ブレード

ログに加え、Application InsightsはKustoクエリを書かずにエクスポートされたGenAIテレメトリーを可視化する組み込みのエージェント(プレビュー)ビューを提供しています。 Copilot Studioがスパンを dependencies テーブルに書き込むと、これらのブレードはそのデータから直接読み込みます:

• エージェントラン: InvokeAgent スパンから構築されたエージェント呼び出し、その持続時間、成功、各ランが属する会話を一覧化します。 いくつかの制限があります。「 既知の制限と考慮事項」で詳しく学びましょう。
• ツール: ExecuteTool スパンを集約し、エージェントがどのツールをどの頻度で、どのように機能させるかを示します。
• モデル:ランを通じたモデルの使用をまとめ、呼び出されたモデルとそのコールパターンを明らかにします。

Application Insightsでエージェントのテレメトリを分析

環境を Application Insights に接続すると、Copilot Studio 内でのテスト時を含め、ユーザーがエージェントと対話した際のエージェント テレメトリ データが記録されます。 ログされたテレメトリデータを閲覧するには、AzureのApplication InsightsリソースのLogsセクションにアクセスしてください。 ここでは Kustoクエリ を使ってデータをクエリ・分析できます。 詳細は 「例クエリ」をご覧ください。

クエリの例

以下のKustoクエリ例は、Application InsightsのdependenciesテーブルからエージェントCopilot Studio会話を再構築したものです。 各ターンでは、すべてのスパンがトレース operation_Id を共有するため、クエリは各トレース内でスパンをルート優先（InvokeAgent スパンをその子スパンより前）に順序付けます。

クエリ1:特定の会話IDに対して完全なトレースを返す

このクエリは、既知の会話1件について、各ルートスパンをその子スパンより前に並べた時系列順で、すべてのスパンを返します。 会話IDのプレースホルダーをエージェントの会話IDに置き換えてください。 カスタムエージェントのテスト中に以下のコマンドを入力して見つけられます: /debug conversationid。

let LatestConvo = "<Conversation ID>"; 
dependencies
| where tostring(customDimensions["gen_ai.conversation.id"]) == LatestConvo
| order by operation_Id asc, iff(name == "InvokeAgent", 0, 1) asc, timestamp asc
| project timestamp, name, id, operation_Id,
          operation_ParentId, duration, target, type, cloud_RoleName,
          resultCode, customDimensions

クエリ2:特定のエージェントの最新の会話を返す

このクエリは指定された時間ウィンドウ内の名前付きエージェントの最新の会話を見つけます。 その会話に含まれるすべてのスパンを、時系列順かつルート優先の順序で返します。 エージェント名のプレースホルダーをエージェント名に置き換えてください。

let Window = 7d;
let AgentName = "<Agent name>";
let LatestConvo = toscalar(
    dependencies
    | where timestamp > ago(Window)
    | where tostring(customDimensions["gen_ai.agent.name"]) == AgentName
    | where isnotempty(tostring(customDimensions["gen_ai.conversation.id"]))
    | top 1 by timestamp desc
    | project tostring(customDimensions["gen_ai.conversation.id"])
);
dependencies
| where timestamp > ago(Window)
| where tostring(customDimensions["gen_ai.conversation.id"]) == LatestConvo
| order by operation_Id asc, iff(name == "InvokeAgent", 0, 1) asc, timestamp asc
| project timestamp, name, id, operation_Id,
          operation_ParentId, duration, target, type, cloud_RoleName,
          resultCode, customDimensions

クエリ3:既知のGenAI OpenTelemetryプロパティを列に展開する

このクエリはクエリ2と同じトレースを返しますが、既知の各OpenTelemetryセマンティックコンベンションキーを独自の名前付き列に解析します。 その結果、ツール名、モデル、ユーザープロンプト、エージェントの返信、会話IDなどの生成AIフィールドを直接ソート、フィルタリング、スキャンできるフラットで明示的に定義されたテーブルが完成します。 エージェント名のプレースホルダーをエージェント名に置き換えてください。

let Window = 7d;
let AgentName = "<Agent name>";
let LatestConvo =
    toscalar(
        dependencies
        | where timestamp > ago(Window)
        | extend
            AgentName_ = tostring(customDimensions["gen_ai.agent.name"]),
            ConversationId_ = tostring(customDimensions["gen_ai.conversation.id"])
        | where AgentName_ == AgentName
        | where isnotempty(ConversationId_)
        | summarize arg_max(timestamp, ConversationId_)
        | project ConversationId_
    );
dependencies
| where timestamp > ago(Window)
| extend
    ConversationId = tostring(customDimensions["gen_ai.conversation.id"])
| where ConversationId == LatestConvo
| extend
    OperationName    = tostring(customDimensions["gen_ai.operation.name"]),
    AgentId          = tostring(customDimensions["gen_ai.agent.id"]),
    AgentName        = tostring(customDimensions["gen_ai.agent.name"]),
    Model            = tostring(customDimensions["gen_ai.request.model"]),
    ToolName         = tostring(customDimensions["gen_ai.tool.name"]),
    ToolType         = tostring(customDimensions["gen_ai.tool.type"]),
    ToolCallId       = tostring(customDimensions["gen_ai.tool.call.id"]),
    ToolArguments    = tostring(customDimensions["gen_ai.tool.call.arguments"]),
    ToolResult       = tostring(customDimensions["gen_ai.tool.call.result"]),
    EnvironmentId    = tostring(customDimensions["env.id"]),
    TenantId         = tostring(customDimensions["microsoft.tenant.id"]),
    ChannelName      = tostring(customDimensions["microsoft.channel.name"]),
    BlueprintId      = tostring(customDimensions["microsoft.a365.agent.blueprint.id"]),
    PlatformId       = tostring(customDimensions["microsoft.a365.agent.platform.id"]),
    ResourceProvider = tostring(customDimensions["resource.provider"]),
    SignalCategory   = tostring(customDimensions["signal.category"]),
    UserId           = tostring(customDimensions["user.id"]),
    UserName         = tostring(customDimensions["user.name"]),
    UserEmail        = tostring(customDimensions["user.email"])
| extend
    InputMessages  = parse_json(tostring(customDimensions["gen_ai.input.messages"])),
    OutputMessages = parse_json(tostring(customDimensions["gen_ai.output.messages"]))
| extend
    UserInput   = tostring(InputMessages[0].parts[0].content),
    AgentOutput = tostring(OutputMessages[0].parts[0].content)
| order by
    operation_Id asc,
    iff(name == "InvokeAgent", 0, 1) asc,
    timestamp asc
| project
    timestamp, name, id, operation_Id, operation_ParentId, OperationName, ConversationId,
    AgentId, AgentName, Model, ToolName, ToolType, ToolCallId, ToolArguments, ToolResult,
    UserInput, AgentOutput, EnvironmentId, TenantId, ChannelName, BlueprintId, PlatformId,
    ResourceProvider, SignalCategory, UserId, UserName, UserEmail, duration, target, type,
    cloud_RoleName, resultCode, customDimensions

クエリ4:すべてのgenAI OpenTelemetryプロパティを動的に展開する

このクエリはクエリ3と同じスパンを返しますが、すべての gen_ai.* キーは customDimensions から動的にアンパックされ、独自の ga_接頭辞付き列に展開されます。 投影は動的であるため、SDKが後に新しい gen_ai.* 属性を出す際にはクエリを変更せずに自動的に表示されます。 エージェント名のプレースホルダーをエージェント名に置き換えてください。

let Window = 7d;
let AgentName = "<Agent name>";
let LatestConvo = toscalar(
    dependencies
    | where timestamp > ago(Window)
    | where tostring(customDimensions["gen_ai.agent.name"]) == AgentName
    | where isnotempty(tostring(customDimensions["gen_ai.conversation.id"]))
    | top 1 by timestamp desc
    | project tostring(customDimensions["gen_ai.conversation.id"])
);
dependencies
| where timestamp > ago(Window)
| where tostring(customDimensions["gen_ai.conversation.id"]) == LatestConvo
| order by operation_Id asc, iff(name == "InvokeAgent", 0, 1) asc, timestamp asc
| mv-apply Key = bag_keys(customDimensions) on (
    where Key startswith "gen_ai."
    | summarize OTelGenAI = make_bag(bag_pack(tostring(Key), customDimensions[tostring(Key)]))
  )
| project timestamp, name, id, operation_Id, operation_ParentId,
          duration, target, type, cloud_RoleName, resultCode,
          OTelGenAI, customDimensions
| evaluate bag_unpack(OTelGenAI, 'ga_')

既知の制限と考慮事項

• この機能は、未認証または マルチテナント エージェント構成 のシナリオをサポートしていません。 したがって、Application Insightsはそれらを記録しません。
• この機能は現在、Microsoftのパブリッククラウド環境でのみ利用可能です。
• 特定の接続済みエージェントのシナリオにおいて、トレース間の親子関係が正しくマッピングされていません。
• 標準ハーネスで動作するエージェントのトレースでは、duration の値は利用できません。
• ターゲットのApplication Insightsリソースでローカル 認証 プロパティをオンにするようにしてください。
• テレメトリのエクスポートはトランザクションではありません。 一時的なサービスイベント中には、少量のデータ損失が発生することがあります。
• スキーマ関連の取り込みアップデートが展開される際にデータ不整合が生じることがあります。
• この機能は TopicStart、 TopicAction、 TopicEndなどのトピック関連イベントを捉えていません。
• トレースおよびスパンIDは現在、OpenTelemetry標準の32文字トレースIDや16文字スパンIDの16進形式の代わりにGUIDベースの表現を使用しています。
• レポートやトラブルシューティングを簡素化するために、エージェントレベルと環境レベルのテレメトリを同じApplication Insightsインスタンスに送信するのは避けてください。
• テレメトリは、GitHub Copilotハーネスで駆動されるエージェントと標準ハーネスで動作するエージェントによって異なる場合があります。
• 環境レベルのApplication Insights構成が、データのレジデンシー、プライバシー、ロールベースのアクセス制御(RBAC)要件を満たしていることを確認しましょう。
• エージェントの応答やツールの引数を含む大規模なログコンテンツは、切り捨てられることがあります。

関連情報

• アプリケーションインサイトを用いたテレメトリー概要
• Application Insightsを用いたエージェントレベルのテレメトリ
• Application Insightsへのデータエクスポート
• Azure アプリケーション Insights