Ympäristötason telemetria Application Insightsilla (esikatselu)

[Tämä artikkeli on esijulkaisuasiakirja, ja se voi muuttua.]

Käytä Azure Application Insightsia valvomaan Copilot Studio -agentin jäljityksiä, jotka on viety hallitusta ympäristöstä. Kun olet konfiguroinut viennin, käytä Azure Monitor ja Application Insightsia agentin suoritusten validointiin, solmujen ja työkalujen suorituksen seuraamiseen, hälytyksien luomiseen sekä räätälöityjen kyselyiden ja dashboardien rakentamiseen operatiivista analyysiä varten.

Tässä artikkelissa selitetään, miten Copilot Studio -agentin jäljitysten ympäristötason vienti Azure Application Insightsiin Power Platformin hallintakeskuksen kautta.

Edellytykset

Ennen kuin asetat datan vientiyhteyden, suorita Export data to Application Insights -edellytykset.

Mitä viedään

Kun otat viennin käyttöön, Copilot Studio -agentin jäljitystelemetria kirjoitetaan Application Insightsiin jäljityssuuntautuneessa, OpenTelemetryn mukaisessa havaittavuusmuodossa, joka tukee tutkimusta, kojelauteita ja hälytyksiä.

Copilot Studio -agentin tapahtumat kirjoitetaan dependencies -tauluun jälkinä. Jokainen viety tapahtuma (InvokeAgent, ExecuteTool ja OutputMessages) on yksi span-rivi (itemType = dependency).

Miten jännevälit muodostavat jäljen

Telemetria noudattaa OpenTelemetryn jäljitys- ja saraumamallia, joka rekonstruoidaan operation_Id ja-sarakkeiden operation_ParentId kautta:

• Jokainen agenttivuoro on oma jäljityksensä, joka tunnistetaan jaetulla operation_Id tiedostolla, jonka avulla Application Insights voi ryhmitellä vuoron ja renderöidä sen end-to-end-transaktionäkymässä.
• Jänne InvokeAgent on sen käännöksen jäljen juuri . Sen ExecuteTool ja siihen liittyvät OutputMessages-spanit sijoittuvat sen alle sisäkkäin, ja jokaisessa on operation_ParentId = InvokeAgent-spanin id.
• Keskustelu kestää useita vuoroja, jokainen erillisenä jäljenä. Ryhmittele tai suodata mukaan gen_ai.conversation.id , jotta yhden keskustelun vuorot yhdistetään takaisin.
• OutputMessages Spanit eivät aina emittoi juurta InvokeAgent , mikä tarkoittaa, että ne voivat (suunnittelun mukaan) saapua ilman vastaavaa vanhemmaa ja esiintyä itsenäisinä, yksittäisen solmun jäljityksinä.

Vientipaketin luominen

Luo vientipaketti ja määritä vientityypiksi Copilot Studio noudattamalla Power Platformin hallintakeskuksen dokumentaation kohdan Vientipaketin luominen ohjeita.

Määrityksen vahvistaminen

Kun olet tallentanut vientikonfiguraation, suorita testikeskustelu agentin kanssa ja varmista, että telemetria saapuu Application Insightsiin. Telemetrian toimitus voi kestää jopa 24 tuntia uusissa kokoonpanoissa. Vahvista se:

• Agent-spanit näkyvät taulukossa dependencies.
• Kunkin vuoron InvokeAgent, ExecuteTool ja OutputMessages jaksot jakavat saman operation_Id.

Application Insights -kentät

Seuraava taulukko näyttää taulukon kentät dependencies sekä mitkä kentät täytetään kullekin kolmesta viedystä agenttitapahtumasta: InvokeAgent, ExecuteTool, ja OutputMessages. Agentti- ja operaatiosemantiikka on joukossa customDimensions (avaimet gen_ai.* , kuten gen_ai.operation.name), eivät natiivisarakkeissa.

customDimensions-ominaisuudet

Jokainen väli sisältää customDimensions JSONin. Seuraava taulukko esittää yleiset avaimet, jotka esiintyvät jokaisessa spanissa:

Tapahtumakohtaiset avaimet

Seuraava taulukko näyttää tapahtumakohtaiset avaimet:

Tutustu nykyiseen skeemaan

Tässä artikkelissa dokumentoitu skeema saattaa kehittyä ajan myötä. Sen sijaan, että luottaisit pelkästään aiemmin mainittuihin taulukoihin, käytä seuraavia kyselyitä tarkistaaksesi uusimman skeeman omassa ympäristössäsi.

Listaa natiivit taulukkosarakkeet

Seuraava kysely palauttaa taulukon saraketason skeeman dependencies . Käytä sitä varmistamaan saatavilla olevat natiivisarakkeet luodessasi kyselyitä, kojelautioita tai hälytyksiä.

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

Löydä customDimension-avaimet (dynaamiset ominaisuudet)

Seuraava kysely listaa kaikki avaimet customDimensions JSON:n sisällä taulukossa dependencies : ominaisuuden nimen, minkä agentin tapahtumat (InvokeAgent, ExecuteTool, OutputMessages), ja otosarvon. Toisin kuin natiivisa sarakeskeema, nämä ominaisuudet ovat dynaamisia, joten kysely pysyy tarkkana, kun SDK lisää uusia gen_ai.* tai muita avaimia. Käytä sitä totuuden elävänä lähteenä saatavilla oleville ominaisuuksille.

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

Valvo vietyä telemetriaa

Käytä Application Insights -lokkeja agentin toiminnan kyselyyn ja agentin tai työkalun suorituksen tutkimiseen. Kaikki viedyt telemetriat sijoittuvat dependencies taulukkoon sulatusina:

• Jokainen agentin vuoro on jäljitys, joka on ryhmitelty yhteisen operation_Id:n mukaan.
• Span InvokeAgent on jäljen juuri; spanit ExecuteTool ja OutputMessages sijoittuvat sen alle sisäkkäin kohdan operation_ParentId kautta.
• Ryhmittele kohdan gen_ai.conversation.id mukaan, jotta saman keskustelun useat vuorot säikeistetään, ja jaa tunnus kohdan _ perusteella, jotta aliagenttien jäljet sisällytetään.

Agenttien (esikatselu) sivut

Lokitietojen lisäksi Application Insights tarjoaa sisäänrakennetut Agentit (esikatselu) -näkymät, jotka visualisoivat vietyn GenAI-telemetrian ilman Kusto-kyselyiden kirjoittamista. Kun Copilot Studio kirjoittaa jännejänteensä dependencies pöydälle, nämä terät lukevat suoraan datasta:

• Agent Runs: Luettelee InvokeAgent-spaneista muodostetut agentin suorituskerrat sekä niiden keston, onnistumisen ja sen, mihin keskusteluun kukin suorituskerta kuuluu. Joitakin rajoituksia on voimassa; lue lisää artikkelista Tunnetut rajoitukset ja huomioitavat.
• Työkalut: Kokoaa avainalueet ExecuteTool näyttääkseen, mitä työkaluja agentit kutsuvat, kuinka usein ja miten he suoriutuvat.
• Mallit: Tiivistää mallin käytön eri ajoissa, esitellen kutsutut mallit ja niiden kutsukuviot.

Analysoi agentin telemetriaa Application Insightsilla

Kun yhdistät ympäristösi Application Insightsiin, se kirjaa agentin telemetriadatan, kun käyttäjät ovat vuorovaikutuksessa agentin kanssa, myös Copilot Studio -testauksen aikana. Nähdäksesi tallennetut telemetriadatan, mene Application Insights -resurssisi Lokit-osioon Azure-ohjelmassa. Täällä voit käyttää Kusto-kyselyitä datan kyselyyn ja analysointiin. Lue lisää esimerkkikyselyistä.

Esimerkkikyselyt

Seuraavat Kusto-kyselyesimerkit rekonstruoivat Copilot Studio -agenttikeskustelut Application dependencies Insightsin taulukosta. Koska jokaisella spanilla on trace operation_Id jokaista vuoroa kohti, kyselyt järjestävät spanit juuri ensin -järjestykseen (span InvokeAgent ennen sen lapsispaneja) kunkin tracen sisällä.

Kysely 1: Palauta täydellinen jäljitys tietylle keskustelutunnukselle

Tämä kysely palauttaa kaikki yhden tunnetun keskustelun spanit aikajärjestyksessä siten, että jokainen juurispani luetellaan ennen sen lapsispaneja. Korvaa Conversation ID :n paikkamerkki agenttisi Conversation ID:llä. Löydät sen syöttämällä seuraavan komennon testatessasi omaa agenttiasi: /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

Kysymys 2: Palauta viimeisin keskustelu tietylle agentille

Tämä kysely löytää nimetyn agentin viimeisimmän keskustelun määritellyn aikarajan sisällä. Se palauttaa jokaisen jakson tuosta keskustelusta samassa kronologisessa järjestyksessä, juurena -järjestyksessä. Korvaa agentin nimen paikkamerkki agenttisi nimellä.

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

Kysely 3: Laajenna tunnetun sukupolven AI:n OpenTelemetrian ominaisuudet sarakkeiksi

Tämä kysely palauttaa saman jäljen kuin kysely 2, mutta se myös jäsentää jokaisen tunnetun OpenTelemetrian semanttisen konventioavaimen omaan nimettyyn sarakkeensa. Tuloksena on tasainen, eksplisiittisesti määritelty taulukko, jossa voit lajitella, suodattaa ja skannata generatiivisia tekoälykenttiä, kuten työkalun nimi, malli, käyttäjäkehotte, agentin vastaus ja keskustelutunniste suoraan. Korvaa agentin nimen paikkamerkki agenttisi nimellä.

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

Kysely 4: Laajenna kaikki genAI:n OpenTelemetrian ominaisuudet dynaamisesti

Tämä kysely palauttaa samat haarat kuin kysely 3, mutta jokainen gen_ai.* avain puretaan dynaamisesti customDimensions omaan ga_-etuliitteen sarakkeensa. Koska projektio on dynaaminen, kaikki SDK:n myöhemmin lähettämät uudet gen_ai.* attribuutit ilmestyvät automaattisesti muuttamatta kyselyä. Korvaa agentin nimen paikkamerkki agenttisi nimellä.

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

Kysely 5: Palauta juuriagentin viimeisin keskustelu kaikkine sen lapsineen, mukaan lukien aliagentit

Tämä kysely palauttaa viimeisimmän keskustelun nimetystä agentista. Se palauttaa kaikki kyseiseen keskusteluun ja kaikkiin sen kutsumiin ensimmäisen tason ala-agentteihin liittyvät spanit. Kun agentti kutsuu toista agenttia työkaluksi, aliagentti perii vanhemman keskustelutunnuksen suffiksilla _<subConversationId> . Koko puu muodostetaan uudelleen hakemalla vastaavuutta ylimmän tason tunnisteen perusteella. Korvaa agentin nimen paikkamerkki agenttisi nimellä.

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

Tunnetut rajoitukset ja seikat

• Arvoa duration ei ole saatavilla perinteisille agenttijäljille.
• Agentin ja työkalun suoritusvirheet eivät tällä hetkellä näy oikein jäljitystiloissa.
• Data-residenssivaatimuksesi perusteella saatat haluta käyttää omia Application Insights -resursseja jokaiselle ympäristöalueelle.
• Aliagentin spanit ovat tällä hetkellä sen InvokeAgent-spanin alaisia, joka kutsui agentin, sen sijaan että ne olisivat oman jälkensä sisällä olevan InvokeAgent-spanin alaisia.
• Jäljitys- ja span-ID:t lähettävät tällä hetkellä GUID-tunnisteina (tarvittaessa etuliitteinä) sen sijaan, että ne olisivat täysin OpenTelemetry-standardin mukaiset 32-hex-char trace ID ja 16-hex-char span ID -kohdistettuina.
• Varmista, että paikallinen tunnistautuminen on käytössä kohdesovellukset Insights -resurssissa.
• Telemetrian vienti ei ole transaktiopohjaista. Väliaikaisten palvelutapahtumien aikana voi tapahtua pieniä määriä datan menetyksiä.
• Tietojen epäjohdonmukaisuuksia voi ilmetä skeema-aiheisten syöttöpäivitysten käyttöönoton yhteydessä.
• Aiheeseen liittyvät tapahtumat, kuten TopicStart, TopicAction, ja TopicEnd ei tallenneta ympäristötason telemetrialla.
• Raportoinnin ja vianmäärityksen yksinkertaistamiseksi vältä lähettämästä sekä agenttitason että ympäristötason telemetriaa samaan Application Insights -instanssiin.
• GitHub Copilot -agenttien lähettämä telemetria voi poiketa niistä agenteista, jotka on rakennettu tavallisilla valjastusvaljakkojen luomiskokemuksella.

Liittyvät tiedot

• Telemetria Application Insightsin kanssa yleiskatsaus
• Agenttitason telemetriaa Application Insightsin avulla
• Tietojen vienti Application Insightsiin
• Azure Application Insights