Telemetria a livello ambiente con Application Insights (anteprima)

[Questo articolo è una documentazione preliminare ed è soggetto a modifiche.]

Usa applicazione Azure Insights per monitorare le tracce degli agenti di Copilot Studio esportate da un ambiente gestito. Dopo aver configurato l'esportazione, usa Monitoraggio di Azure e Application Insights per validare le esecuzioni degli agenti, monitorare l'esecuzione di nodi e strumenti, creare avvisi e creare query e dashboard personalizzati per l'analisi operativa.

Questo articolo spiega come configurare l'esportazione a livello di ambiente delle tracce degli agenti di Copilot Studio verso applicazione Azure Insights tramite il centro di amministrazione Power Platform.

Prerequisiti

Prima di configurare la connessione di esportazione dati, completa i prerequisiti di Esporta dati in Application Insights.

Elementi esportati

Quando abiliti l'esportazione, la telemetria di tracce dell'agente di Copilot Studio viene scritta su Application Insights in un formato di osservabilità orientato alle tracce e allineato a OpenTelemetry, che supporta indagini, dashboard e allarme.

Gli eventi degli agenti di Copilot Studio vengono scritti nella tabella dependencies come intervalli. Ogni evento esportato (InvokeAgent, ExecuteTool, e OutputMessages) è una singola riga di campata (itemType = dependency).

Come le span formano una traccia

La telemetria segue il modello di trace e span di OpenTelemetry, ricostruito attraverso le colonne operation_Id e operation_ParentId:

• Ogni turno dell'agente è una propria traccia, identificata da un operation_Id condiviso che consente ad Application Insights di raggruppare il turno e visualizzarlo nella vista end-to-end della transazione.
• L'InvokeAgent intervallo è la radice della traccia del suo turno. Il relativo ExecuteTool e gli OutputMessages span collegati sono annidati sotto di esso, ciascuno con operation_ParentId = lo InvokeAgent dello span id.
• Una conversazione si estende su più turni, ciascuno emesso come traccia separata. Raggruppa o filtra per gen_ai.conversation.id per ricollegare i turni di una stessa conversazione.
• I sotto-agenti funzionano come traccia autonoma. Quando un agente chiama un altro agente come strumento, il sotto-agente eredita l'ID della conversazione del genitore con il suffisso _<subConversationId>, ad esempio <rootConversationId>_<subConversationId>. Dividi gen_ai.conversation.id in base a _ e abbina la porzione radice per ricostruire l'albero completo multi-agente (scopri di più in query 5).
• OutputMessages Gli span non sempre emettono una InvokeAgent radice, il che significa che possono (per design) arrivare senza un genitore corrispondente e apparire come una traccia autonoma a singolo nodo.

Creare un pacchetto di esportazione

Crea un pacchetto di esportazione con il tipo di esportazione impostato su Copilot Studio seguendo le istruzioni in Crea un pacchetto di esportazione della documentazione del centro di amministrazione Power Platform.

Convalidare la configurazione

Dopo aver salvato la configurazione di esportazione, avvia una conversazione di test con l'agente e conferma che la telemetria arriva in Application Insights. La consegna della telemetria può richiedere fino a 24 ore con nuove configurazioni. Verificare che:

• Gli span degli agenti compaiono nella tabella dependencies.
• Gli intervalli InvokeAgent, ExecuteTool e OutputMessages di ogni turno condividono un operation_Id.

Campi di Application Insights

La tabella seguente mostra i campi nella dependencies tabella e quali campi sono popolati per ciascuno dei tre eventi dell'agente esportato: InvokeAgent, ExecuteTool, e OutputMessages. La semantica di agente e operazione è in customDimensions (le gen_ai.* chiavi, come gen_ai.operation.name), non nelle colonne native.

Proprietà di customDimensions

Ogni intervallo include il JSON customDimensions. La tabella seguente mostra le chiavi comuni presenti in ogni intervallo:

Chiavi specifiche per evento

La tabella seguente mostra le chiavi specifiche per evento:

Scopri lo schema attuale

Lo schema documentato in questo articolo potrebbe evolversi nel tempo. Invece di affidarti solo alle tabelle menzionate in precedenza, usa le seguenti domande per esaminare lo schema più recente in tempo reale nel tuo ambiente.

Elenca le colonne native delle tabelle

La query seguente restituisce lo schema a livello di colonna della dependencies tabella. Usalo per confermare le colonne native disponibili quando crei query, dashboard o avvisi.

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

Scopri chiavi personalizzate Dimensions (proprietà dinamiche)

La seguente query elenca tutte le chiavi all'interno del customDimensions JSON nella dependencies tabella: il nome della proprietà, su quali eventi dell'agente appare (InvokeAgent, ExecuteTool, OutputMessages), e un valore di esempio. A differenza dello schema a colonne nativo, queste proprietà sono dinamiche, quindi questa query rimane accurata mentre l'SDK aggiunge nuove gen_ai.* o altre chiavi. Usalo come fonte viva di verità per gli attributi disponibili.

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

Monitorare la telemetria esportata

Usa i Log di Application Insights per interrogare l'attività degli agenti e indagare sull'esecuzione di agenti o strumenti. La telemetria esportata confluisce nella dependencies tabella come span:

• Ogni turno dell'agente è una traccia, raggruppata tramite un operation_Id condiviso.
• Lo InvokeAgent span è lo span radice della traccia; gli ExecuteTool e OutputMessages span sono annidati al di sotto di esso tramite operation_ParentId.
• Raggruppa per gen_ai.conversation.id i turni multipli della stessa conversazione e suddividi tale ID in corrispondenza di _ per includere le tracce dei sub-agenti.

Lame degli agenti (anteprima)

Oltre a Logs, Application Insights fornisce viste Agents (preview) predefinite che visualizzano la telemetria GenAI esportata senza dover scrivere query Kusto. Quando Copilot Studio scrive i propri span nella tabella dependencies, queste blade leggono direttamente da tali dati:

• Esecuzioni dell'agente: Elenca le invocazioni dell'agente generate dagli intervalli InvokeAgent, con la relativa durata, l'esito e la conversazione a cui appartiene ogni esecuzione. Si applicano alcune limitazioni; scopri di più in Limitazioni e considerazioni note.
• Strumenti: Aggrega gli ExecuteTool intervalli per mostrare quali strumenti chiamano gli agenti, con quale frequenza e come si comportano.
• Modelli: Riassume l'uso dei modelli tra le run, evidenziando i modelli invocati e i loro modelli di chiamata.

Analizza la telemetria degli agenti con Application Insights

Dopo aver collegato il tuo ambiente ad Application Insights, registra i dati di telemetria degli agenti quando gli utenti interagiscono con l'agente, anche durante i test all'interno di Copilot Studio. Per visualizzare i dati di telemetria registrati, vai alla sezione Log della tua risorsa Application Insights in Azure. Qui puoi usare le query Kusto per interrogare e analizzare i tuoi dati. Scopri di più in Query di esempio.

Interrogazioni di esempio

I seguenti esempi di query Kusto ricostruiscono le conversazioni degli agenti di Copilot Studio dalla tabella dependencies in Application Insights. Poiché a ogni turno tutti gli span condividono una traccia operation_Id, le query ordinano gli span partendo dalla radice (lo span InvokeAgent prima dei relativi span figlio) all'interno di ogni traccia.

Query 1: Restituisci una traccia completa per un ID di conversazione specifico

Questa query restituisce tutti gli span di una conversazione nota, ordinati cronologicamente, con ogni span radice elencato prima dei relativi span figli. Sostituisci il segnaposto Conversation ID con l'ID conversazione del tuo agente. Puoi trovarlo inserendo il seguente comando mentre testi il tuo agente custom: /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

Domanda 2: Restituisci l'ultima conversazione per un agente specifico

Questa query trova la conversazione più recente per un agente nominato entro la finestra temporale specificata. Restituisce ogni intervallo di quella conversazione nello stesso ordine cronologico, radice prima. Sostituisci il nome dell'agente provvisorio con quello del tuo agente.

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

Query 3: Espandere le proprietà note di OpenTelemetry di GenAI in colonne

Questa query restituisce la stessa traccia della query 2, ma suddivide anche ogni chiave nota delle convenzioni semantiche di OpenTelemetry in una colonna dedicata con nome proprio. Il risultato è una tabella piatta ed esplicitamente definita dove puoi ordinare, filtrare e scansionare direttamente i campi dell'IA generativa come nome dello strumento, modello, prompt utente, risposta dell'agente e ID conversazione. Sostituisci il nome dell'agente provvisorio con quello del tuo agente.

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

Query 4: Espandi dinamicamente tutte le proprietà di OpenTelemetry di genAI

Questa query restituisce gli stessi intervalli della query 3, ma ogni chiave gen_ai.* viene estratta dinamicamente da customDimensions in una propria colonna con prefisso ga_. Poiché la proiezione è dinamica, qualsiasi nuovo gen_ai.* attributo emettato dall'SDK appare automaticamente senza modificare la query. Sostituisci il nome dell'agente provvisorio con quello del tuo agente.

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_')

Query 5: Restituisci l'ultima conversazione per un root agent con tutti i suoi figli, inclusi i sotto-agenti

Questa query restituisce la conversazione più recente per un agente specificato per nome. Restituisce ogni intervallo di quella conversazione e di tutti i sotto-agenti di primo livello che ha invocato. Quando un agente chiama un altro agente come strumento, il sotto-agente eredita l'ID della conversazione del genitore con il suffisso _<subConversationId>. L'intero albero viene ricostruito facendo coincidenza sull'ID di livello superiore. Sostituisci il nome dell'agente provvisorio con quello del tuo agente.

let Window = 7d;
let AgentName = "<Agent name>";
let LatestRoot =
    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)
        | where ConversationId !has "_"
        | summarize arg_max(timestamp, ConversationId)
        | project ConversationId
    );
dependencies
| where timestamp > ago(Window)
| extend
    ConversationId = tostring(customDimensions["gen_ai.conversation.id"]),
    AgentName_ = tostring(customDimensions["gen_ai.agent.name"]),
    ToolName = tostring(customDimensions["gen_ai.tool.name"]),
    ToolResult = tostring(customDimensions["gen_ai.tool.callresult"])
| where isnotempty(ConversationId)
| where ConversationId == LatestRoot
    or ConversationId startswith strcat(LatestRoot, "_")
| extend
    Depth = countof(ConversationId, "_"),
    AgentRole = iff(ConversationId == LatestRoot, "root", "sub-agent")
| 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 timestamp asc
| project
    timestamp, name, AgentRole, Depth, AgentName, ToolName, ToolResult, UserInput,
    AgentOutput, id, operation_Id, operation_ParentId, ConversationId, duration,
    target, type, cloud_RoleName, resultCode, customDimensions

Limitazioni e considerazioni note

• Il duration valore non è disponibile per le tracce classiche degli agenti.
• Gli errori di esecuzione degli agenti e degli strumenti non si riflettono attualmente correttamente negli stati delle tracce.
• In base alle tue esigenze di residenza dati, potresti voler utilizzare risorse dedicate a Application Insights per ogni regione ambientale.
• Gli span del sotto-agente hanno attualmente come padre lo span InvokeAgent che ha invocato l'agente, anziché lo span InvokeAgent all'interno della propria traccia.
• Gli ID di traccia e di span vengono attualmente emessi come GUID (con prefisso, ove necessario), anziché come ID di traccia di 32 caratteri esadecimali e ID di span di 16 caratteri esadecimali, pienamente conformi e allineati allo standard OpenTelemetry.
• Assicurati che l'autenticazione locale sia abilitata sulla risorsa target Application Insights.
• L'esportazione della telemetria non è transazionale. Durante eventi di servizio transitorio, possono verificarsi piccole perdite di dati.
• Potrebbero verificarsi incongruenze nei dati durante il lancio degli aggiornamenti di ingestione relativi allo schema.
• Eventi legati a argomenti come TopicStart, TopicAction, e TopicEnd non vengono catturati con la telemetria a livello ambientale.
• Per semplificare la reportistica e la risoluzione dei problemi, evita di inviare sia telemetria a livello di agente che a livello di ambiente alla stessa istanza di Application Insights.
• La telemetria emessa per gli agenti creati nella nuova esperienza di creazione degli agenti potrebbe differire da quella degli agenti creati nell'esperienza classica di creazione degli agenti.

Informazioni pertinenti

• Panoramica della telemetria con Application Insights
• Telemetria a livello di agente con Application Insights
• Esporta i dati in Application Insights
• applicazione Azure Insights