Miljönivåtelemetri med Application Insights (förhandsgranskning)

[Denna artikel är en förhandsversion av dokumentationen och kan komma att ändras.]

Använd Azure Application Insights för att övervaka Copilot Studio-agentspår som exporteras från en hanterad miljö. Efter att du konfigurerat export, använd Azure Monitor och Application Insights för att validera agentkörningar, övervaka nod- och verktygskörning, skapa varningar och bygga anpassade frågor och dashboards för operativ analys.

Den här artikeln förklarar hur man konfigurerar miljönivåexport av Copilot Studio-agentspår till Azure Application Insights via Power Platform-administrationscentret.

Förutsättningar

Innan du sätter upp dataexportanslutningen, fyll i förkunskaperna för att exportera data till Application Insights.

Vad exporteras

När du aktiverar export skrivs Copilot Studio-agentens trace-telemetri till Application Insights i ett spårorienterat, OpenTelemetry-anpassat observabilitetsformat som stödjer undersökning, instrumentpaneler och varningar.

Copilot Studio-agenthändelser skrivs i dependencies tabellen som spann. Varje exporterad händelse (InvokeAgent, ExecuteTool och OutputMessages) är en enskild span-rad (itemType = dependency).

Hur spann bildar ett spår

Telemetrin följer OpenTelemetrys spår- och spannmodell, rekonstruerad genom kolumnerna operation_Id och operation_ParentId:

• Varje agenttur är sin egen trace, identifierad av en delad operation_Id ruta som gör det möjligt för Application Insights att gruppera vändningen och rendera den i end-to-end-transaktionsvyn.
• Spannet InvokeAgent är roten i spårningen för den turen. Dess ExecuteTool och anslutna OutputMessages-span är nästlade under det, och vart och ett har operation_ParentId = InvokeAgent-spanets id.
• En konversation sträcker sig över flera turer, som var och en avges som ett separat spår. Gruppera eller filtrera efter gen_ai.conversation.id för att knyta ihop vändningarna i en konversation igen.
• OutputMessages spann genererar inte alltid ett InvokeAgent-rootspann, vilket innebär att de avsiktligt kan komma utan någon matchande förälder och visas som ett fristående spår med en enda nod.

Skapa ett exportpaket

Skapa ett exportpaket med exporttypen inställd på Copilot Studio genom att följa instruktionerna i Create an export package av Power Platform admincenter-dokumentationen.

Verifiera konfigurationen

Efter att du sparat exportkonfigurationen, kör en testkonversation med agenten och bekräfta att telemetrin anländer till Application Insights. Telemetrileverans kan ta upp till 24 timmar på nya konfigurationer. Verifiera att:

• Agentspann visas i dependencies tabellen.
• För varje tur delar InvokeAgent-, ExecuteTool- och OutputMessages-spannen ett operation_Id.

Fält för applikationsinsikter

Följande tabell visar fälten i tabellen dependencies och vilka fält som fylls i för var och en av de tre exporterade agenthändelserna: InvokeAgent, , ExecuteTooloch OutputMessages. Agent- och operationssemantik finns i customDimensions (nycklarna gen_ai.* , såsom gen_ai.operation.name), inte i de ursprungliga kolumnerna.

customDimensions-egenskaper

Varje spann inkluderar customDimensions JSON. Följande tabell visar vanliga nycklar som förekommer på varje spann:

Händelsespecifika nycklar

Följande tabell visar de händelsespecifika nycklarna:

Upptäck det aktuella schemat

Schemat som dokumenteras i denna artikel kan utvecklas över tid. Istället för att enbart förlita dig på de tidigare nämnda tabellerna, använd följande frågor för att inspektera det senaste schemat live i din egen miljö.

Lista över inbyggda tabellkolumner

Följande fråga returnerar tabellens kolumnnivåschema dependencies . Använd den för att bekräfta tillgängliga inbyggda kolumner när du bygger frågor, instrumentpaneler eller aviseringar.

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

Upptäck customDimensions-nycklar (dynamiska egenskaper)

Följande fråga listar varje nyckel i JSON:en customDimensions i dependencies tabellen: egenskapsnamnet, vilka agenthändelser den visas på (InvokeAgent, ExecuteTool, OutputMessages), och ett exempelvärde. Till skillnad från det inbyggda kolumnschemat är dessa egenskaper dynamiska, så denna fråga förblir korrekt när SDK:n lägger till nya gen_ai.* eller andra nycklar. Använd den som den levande sanningskällan för tillgängliga attribut.

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

Övervaka exporterad telemetri

Använd Application Insights Logs för att fråga om agentaktivitet och undersöka agent- eller verktygskörningar. All telemetri som exporteras hamnar i dependencies-tabellen som span:

• Varje agentomgång är ett spår, grupperat med hjälp av en gemensam operation_Id.
• InvokeAgent-spannet är rotspannet i spårningen; ExecuteTool- och OutputMessages-spannen är nästlade under det via operation_ParentId.
• Gruppera efter gen_ai.conversation.id för att samla flera omgångar i samma konversation i en tråd, och dela upp det ID:t vid _ för att inkludera spårningar för underagenter.

Agents (förhandsvisning) blad

Utöver loggar tillhandahåller Application Insights inbyggda agentvyer (förhandsvisning) som visualiserar den exporterade GenAI-telemetrin utan att skriva Kusto-frågor. När Copilot Studio skriver sina spann till dependencies bordet läser dessa blad direkt från den datan:

• Agentkörningar: Visar agentanrop skapade från InvokeAgent-spannen, med deras varaktighet, om de lyckades och vilken konversation varje körning tillhör. Vissa begränsningar gäller; Läs mer i Kända begränsningar och överväganden.
• Verktyg: Sammanställer ExecuteTool-spanen och visar vilka verktyg agenterna anropar, hur ofta och hur de presterar.
• Modeller: Sammanfattar modellanvändning över körningar, visar de anropade modellerna och deras anropsmönster.

Analysera agenttelemetri med Application Insights

Efter att du anslutit din miljö till Application Insights loggar den agentens telemetridata när användare interagerar med agenten, inklusive under testning i Copilot Studio. För att se de loggade telemetridatana, gå till avsnittet Loggar i din Application Insights-resurs i Azure. Här kan du använda Kusto-frågor för att söka och analysera dina data. Läs mer i exempelfrågor.

Exempel på förfrågningar

Följande exempel på Kusto-frågor återskapar Copilot Studio-agentkonversationer dependencies från tabellen i Application Insights. Eftersom varje span delar en trace operation_Id för varje tur, ordnar frågorna span med roten först (spanet InvokeAgent före dess underordnade span) inom varje trace.

Fråga 1: Returnera en fullständig spårning för ett specifikt konversations-ID

Denna fråga returnerar varje span för en viss känd konversation, sorterade kronologiskt där varje rotspan listas före sina underordnade span. Byt ut platshållaren Conversation ID mot agentens konversations-ID. Du kan hitta den genom att ange följande kommando när du testar din anpassade agent: /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

Fråga 2: Returnera den senaste konversationen för en specifik agent

Denna fråga hittar den senaste konversationen för en namngiven agent inom det angivna tidsfönstret. Den returnerar varje span för den konversationen i samma kronologiska ordning, med roten först. Byt ut platshållaren för agentnamnet mot din agents namn.

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

Fråga 3: Utöka kända genAI OpenTelemetriry-egenskaper till kolumner

Denna fråga returnerar samma spår som fråga 2, men den parsar också varje känd OpenTelemetri-semantikkonventionsnyckel till sin egen namngivna kolumn. Resultatet är en platt, explicit definierad tabell där du kan sortera, filtrera och skanna generativa AI-fält som verktygsnamn, modell, användarprompt, agentsvar och konversations-ID direkt. Byt ut platshållaren för agentnamnet mot din agents namn.

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

Fråga 4: Expandera alla genAI OpenTelemetriry-egenskaper dynamiskt

Denna fråga returnerar samma intervall som fråga 3, men varje nyckel i gen_ai.* packas upp dynamiskt från customDimensions till en egen kolumn med prefixet ga_. Eftersom projektionen är dynamisk visas alla nya gen_ai.* attribut som SDK:n skickar ut senare automatiskt utan att frågan ändras. Byt ut platshållaren för agentnamnet mot din agents namn.

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

Fråga 5: Returnera den senaste konversationen för en root-agent med alla dess barn, inklusive underagenter

Denna fråga returnerar den senaste konversationen för en namngiven agent. Den returnerar varje spårningsspann för den konversationen och för alla underagenter på första nivån som den anropade. När en agent anropar en annan agent som verktyg ärver underagenten förälderns konversations-ID med suffixet _<subConversationId>. Hela trädet rekonstrueras genom att matcha det översta nivå-ID:t. Byt ut platshållaren för agentnamnet mot din agents namn.

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

Kända begränsningar och överväganden

• Värdet duration finns inte tillgängligt för spår av agenter som drivs av standardkabeln.
• Fel i agent- och verktygsexekvering återspeglas för närvarande inte korrekt i spårningsstatus.
• Baserat på dina krav på dataresidens kan du vilja använda dedikerade Application Insights-resurser för varje miljöregion.
• Subagent-spann är för närvarande föräldraspanet till det InvokeAgent spann som anropade agenten, istället för spannet InvokeAgent inom deras eget spår.
• Trace- och span-ID:n genereras för närvarande som GUID:er (med prefix där det behövs) i stället för som 32 tecken långa hexadecimala trace-ID:n och 16 tecken långa hexadecimala span-ID:n helt i linje med OpenTelemetry-standarden.
• Se till att lokal autentisering är aktiverad på den aktuella applikationsinsiktsresursen.
• Telemetriexport är inte transaktionell. Under tillfälliga servicehändelser kan små mängder dataförlust uppstå.
• Datainkonsekvenser kan uppstå när schemarelaterade inmatningsuppdateringar rullas ut.
• Ämnesrelaterade händelser som TopicStart, TopicAction, och TopicEnd fångas inte med miljönivåtelemetri.
• För att förenkla rapportering och felsökning, undvik att skicka både agentnivå- och miljönivåtelemetri till samma Application Insights-instans.
• Telemetrin som genereras för agenter som skapats i redigeringsupplevelsen för agenter som drivs av GitHub Copilot-ramverket kan skilja sig från telemetrin för agenter som skapats i redigeringsupplevelsen för agenter som drivs av standardramverket.

Relaterad information

• Översikt av telemetri med applikationsinsikter
• Agentnivåtelemetri med Application Insights
• Exportera data till Application Insights
• Azure Application Insights