Telemetrie op omgevingsniveau met Application Insights (preview)

[Dit artikel maakt deel uit van de voorlopige documentatie en kan nog veranderen.]

Gebruik Azure-toepassing Insights om Copilot Studio-agenttraces te monitoren die vanuit een beheerde omgeving worden geëxporteerd. Nadat je export hebt geconfigureerd, gebruik je Azure Monitor en Application Insights om agentruns te valideren, de uitvoering van nodes en tools te monitoren, alerts te maken en aangepaste queries en dashboards te bouwen voor operationele analyse.

Dit artikel legt uit hoe je omgevingsniveau exporteert van Copilot Studio agent traces naar Azure-toepassing Insights via het Power Platform admin center.

Prerequisites

Voordat je de data-exportverbinding opzet, voltooi je de vereisten van Export data naar Application Insights.

Wat wordt geëxporteerd

Wanneer u export inschakelt, wordt agenttracetelemetrie van Copilot Studio weggeschreven naar Application Insights in een tracegeoriënteerd, op OpenTelemetry afgestemd observeerbaarheidsformaat dat analyse, dashboards en waarschuwingen ondersteunt.

Gebeurtenissen van Copilot Studio-agents worden als spans naar de tabel dependencies geschreven. Elke geëxporteerde gebeurtenis (InvokeAgent, ExecuteTool en OutputMessages) is één spanrij (itemType = dependency).

Hoe spans een trace vormen

De telemetrie volgt het OpenTelemetry-trace-en-spanmodel, gereconstrueerd via de operation_Id en operation_ParentId kolommen:

• Elke agent turn is een eigen trace, geïdentificeerd door een gedeelde operation_Id trace, waardoor Application Insights de turn kan groeperen en renderen in de end-to-end transactieweergave.
• De span InvokeAgent is de root van de trace van zijn beurt. De ExecuteTool ervan en verbonden OutputMessages-spans zijn daaronder genest, elk met operation_ParentId = de id van de InvokeAgent-span.
• Een gesprek omvat meerdere beurten, waarbij elke beurt als een afzonderlijke trace wordt verzonden. Groepeer of filter op gen_ai.conversation.id om de beurten van één gesprek weer samen te brengen.
• OutputMessages-spans zenden niet altijd een InvokeAgent-root uit, wat betekent dat ze (zo bedoeld) zonder een bijpassend bovenliggend element kunnen verschijnen en als een op zichzelf staande trace met één knoop kunnen verschijnen.

Een exportpakket maken

Maak een exportpakket aan met het exporttype ingesteld op Copilot Studio door de instructies in Create a exportpackage van de Power Platform admin center-documentatie te volgen.

De configuratie valideren

Nadat je de exportconfiguratie hebt opgeslagen, voer je een testgesprek uit met de agent en bevestig dat telemetrie aankomt in Application Insights. Telemetrielevering kan tot 24 uur duren bij nieuwe configuraties. Valideer dat:

• Agent-spans worden weergegeven in de tabel dependencies.
• De InvokeAgent, ExecuteTool en OutputMessages-spans van elke beurt delen een operation_Id.

Application Insights-velden

De volgende tabel toont de velden in de dependencies tabel, en welke velden worden ingevuld voor elk van de drie geëxporteerde agentgebeurtenissen: InvokeAgent, ExecuteTool, en OutputMessages. De semantiek van agenten en bewerkingen staat in customDimensions (de sleutels in gen_ai.*, zoals gen_ai.operation.name), niet in de oorspronkelijke kolommen.

customDimensions-eigenschappen

Elke span bevat de JSON customDimensions. De volgende tabel toont veelvoorkomende sleutels die op elke span voorkomen:

Gebeurtenisspecifieke sleutels

De volgende tabel toont de gebeurtenisspecifieke sleutels:

Ontdek het huidige schema

Het schema dat in dit artikel wordt gedocumenteerd, kan in de loop van de tijd evolueren. In plaats van alleen te vertrouwen op de eerder genoemde tabellen, gebruik de volgende queries om het nieuwste schema live in uw eigen omgeving te inspecteren.

Lijst met systeemeigen tabelkolommen

De volgende query geeft het kolomniveau-schema van de dependencies tabel terug. Gebruik dit om te controleren welke native kolommen beschikbaar zijn bij het maken van query's, dashboards of waarschuwingen.

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

Ontdek customDimensions-sleutels (dynamische eigenschappen)

De volgende query vermeldt elke sleutel binnen de customDimensions JSON in de dependencies tabel: de eigenschapsnaam, op welke agent-events deze verschijnt (InvokeAgent, ExecuteTool, ), OutputMessagesen een voorbeeldwaarde. In tegenstelling tot het native kolomschema zijn deze eigenschappen dynamisch, dus deze query blijft accuraat terwijl de SDK nieuwe gen_ai.* of andere sleutels toevoegt. Gebruik het als de levende bron van waarheid voor beschikbare attributen.

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

Geëxporteerde telemetrie controleren

Gebruik de Application Insights Logs om agentactiviteit te bevragen en de uitvoering van agenten of tools te onderzoeken. Alle geëxporteerde telemetrie komt als spans terecht in de dependencies-tabel:

• Elke agentbeurt is een trace, gegroepeerd op basis van een gedeelde operation_Id.
• De InvokeAgent-span is de trace-root; de ExecuteTool- en OutputMessages-spans zijn daaronder genest via operation_ParentId.
• Groepeer op gen_ai.conversation.id om meerdere beurten van hetzelfde gesprek in dezelfde thread te groeperen, en splits die id op _ om traces van subagents op te nemen.

Agents (preview) blades

Naast logs biedt Application Insights ingebouwde Agents (preview) weergaven die de geëxporteerde GenAI-telemetrie visualiseren zonder Kusto-queries te schrijven. Terwijl Copilot Studio zijn spans naar de tabel dependencies schrijft, lezen deze blades direct uit die gegevens:

• Agent runs: Geeft een lijst van agent-invocations die zijn opgebouwd uit de InvokeAgent spans, met hun duur, succes en het gesprek waartoe elke run hoort. Er gelden enkele beperkingen; Lees meer in Bekende beperkingen en overwegingen.
• Tools: Verzamelt de ExecuteTool spans om te laten zien welke tools de agenten bellen, hoe vaak en hoe ze presteren.
• Modellen: Vat het modelgebruik over runs samen, waarbij de aangeroepen modellen en hun aanroeppatronen worden getoond.

Analyseer agenttelemetrie met Application Insights

Nadat je je omgeving verbindt met Application Insights, registreert deze agent-telemetriegegevens wanneer gebruikers met de agent interacteren, ook tijdens testen binnen Copilot Studio. Om de geregistreerde telemetriegegevens te bekijken, ga naar het Logs-gedeelte van je Application Insights-resource in Azure. Hier kun je Kusto-queries gebruiken om je data te bevragen en te analyseren. Lees meer in voorbeeldzoekopdrachten.

Voorbeeldvragen

De volgende Kusto-queryvoorbeelden reconstrueren de gesprekken van Copilot Studio-agenten uit de dependencies tabel in Application Insights. Omdat elke span een trace-operation_Id per beurt deelt, rangschikken de query’s spans met eerst de root (de InvokeAgent-span vóór de onderliggende spans) binnen elke trace.

Query 1: Geef een volledige trace terug voor een specifieke conversatie-ID

Deze query retourneert alle spans van een bekende conversatie, chronologisch geordend, waarbij elke root span vóór de onderliggende child spans wordt weergegeven. Vervang de plaatsaanduiding Conversation ID door de gespreks-ID van je agent. Je kunt het vinden door het volgende commando in te voeren tijdens het testen van je aangepaste 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

Vraag 2: Stuur het laatste gesprek terug voor een specifieke agent

Deze query vindt het meest recente gesprek voor een benoemde agent binnen het opgegeven tijdsvenster. Het retourneert elke span van dat gesprek in dezelfde chronologische volgorde, met de root eerst. Vervang de plaatsvervanger van de naam van de agent door de naam van je agent.

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

Vraag 3: Breid bekende genAI OpenTelemetrie-eigenschappen uit tot kolommen

Deze query geeft dezelfde trace terug als query 2, maar parselt ook elke bekende OpenTelemetrie-semantie-conventiesleutel in een eigen benoemde kolom. Het resultaat is een platte, expliciet gedefinieerde tabel waarin je de generatieve AI-velden zoals toolnaam, model, gebruikersprompt, agentrespons en gespreks-ID direct kunt sorteren, filteren en scannen. Vervang de plaatsvervanger van de naam van de agent door de naam van je agent.

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

Vraag 4: Breid alle genAI OpenTelemetrie-eigenschappen dynamisch uit

Deze query retourneert dezelfde spans als query 3, maar elke gen_ai.*-sleutel wordt dynamisch uitgepakt vanuit customDimensions naar een eigen kolom met het voorvoegsel ga_. Omdat de projectie dynamisch is, verschijnt elk nieuw gen_ai.* attribuut dat de SDK later uitzendt automatisch zonder dat de query wordt gewijzigd. Vervang de plaatsvervanger van de naam van de agent door de naam van je agent.

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: retourneer het nieuwste gesprek voor een root-agent met alle onderliggende, inclusief subagenten

Deze query geeft het meest recente gesprek terug voor een benoemde agent. Het retourneert elke span voor dat gesprek en voor alle subagenten op het eerste niveau die het heeft aangeroepen. Wanneer een agent een andere agent oproept als hulpmiddel, erft de subagent de gespreks-ID van de ouder met een _<subConversationId> achtervoegsel. De hele structuur wordt gereconstrueerd door af te stemmen met de id op het hoogste niveau. Vervang de plaatsvervanger van de naam van de agent door de naam van je agent.

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

Bekende beperkingen en overwegingen

• De waarde duration is niet beschikbaar voor traceringen van agenten die gebruikmaken van de standaard-harness.
• Agent- en tool-uitvoeringsfouten worden momenteel niet correct weergegeven in trace-statussen.
• Afhankelijk van je gegevensresidentievereisten kun je speciale Application Insights-bronnen gebruiken voor elke omgevingsregio.
• Subagent-spans hebben momenteel als bovenliggende span de InvokeAgent-span die de agent heeft aangeroepen, in plaats van de InvokeAgent-span binnen hun eigen trace.
• Trace- en span-id's worden momenteel als GUID's uitgezonden (met een prefix waar nodig), in plaats van volledig in overeenstemming te zijn met de OpenTelemetry-standaard voor een trace-id van 32 hexadecimale tekens en een span-id van 16 hexadecimale tekens.
• Zorg ervoor dat lokale authenticatie is ingeschakeld op de doelbron van Application Insights.
• Telemetrie-export is niet transactioneel. Tijdens tijdelijke servicegebeurtenissen kunnen kleine hoeveelheden dataverlies optreden.
• Gegevensinconsistenties kunnen optreden wanneer schema-gerelateerde invoerupdates worden uitgerold.
• Onderwerpgerelateerde gebeurtenissen zoals TopicStart, TopicAction, en TopicEnd worden niet vastgelegd met omgevingsniveau telemetrie.
• Om rapportage en probleemoplossing te vereenvoudigen, moet je voorkomen dat zowel agent- als omgevingsniveau telemetrie naar dezelfde Application Insights-instantie wordt gestuurd.
• De telemetrie die wordt uitgezonden voor agents die zijn gemaakt in de agents die worden aangestuurd door het GitHub Copilot-harnas, kan verschillen van de telemetrie voor agents die zijn gemaakt in de ontwerpervaring voor agents die worden aangestuurd door het standaardharnas.

Verwante informatie

• Overzicht van telemetrie met applicatieinzichten
• Telemetrie op agentniveau met Application Insights
• Exporteer data naar Application Insights
• Azure-toepassing Insights