Telemetria na poziomie środowiska z Application Insights (podgląd)

[Ten artykuł to dokumentacja wstępna, która może ulec zmianie].

Użyj aplikacja systemu Azure Insights do monitorowania śladów agentów Copilot Studio eksportowanych z środowiska zarządzanego. Po skonfigurowaniu eksportu użyj usług Azure Monitor i Application Insights do weryfikowania uruchomień agentów, monitorowania wykonywania węzłów i narzędzi, tworzenia alertów oraz niestandardowych zapytań i pulpitów nawigacyjnych do analizy operacyjnej.

Ten artykuł wyjaśnia, jak skonfigurować eksport śledzeń agentów Copilot Studio na poziomie środowiska do usługi aplikacja systemu Azure Insights za pomocą centrum administracyjnego Power Platform.

Wymagania wstępne

Przed skonfigurowaniem połączenia eksportu danych wypełnij wymagania wstępne Eksportuj dane do Application Insights.

Co jest eksportowane

Po włączeniu eksportu telemetria śladów agentów programu Copilot Studio jest zapisywana w usłudze Application Insights w ukierunkowanym na ślady formacie wglądu zgodnym z OpenTelemetry, który obsługuje badania, pulpity nawigacyjne i alerty.

Zdarzenia agentów programu Copilot Studio są zapisywane w tabeli dependencies jako zasięgi. Każde wyeksportowane zdarzenie (InvokeAgent, ExecuteTool i OutputMessages) to pojedynczy wiersz span (itemType = dependency).

Jak zasięgi tworzą ślad

Telemetria jest zgodna z modelem śladów i zasięgów OpenTelemetry, odtwarzanym na podstawie kolumn operation_Id i operation_ParentId:

• Każda tura agenta jest osobnym śladem, identyfikowanym za pomocą wspólnego elementu operation_Id, dzięki któremu usługa Application Insights może grupować tę turę i wyświetlać ją w kompleksowym widoku transakcji.
• Zasięg InvokeAgent jest poziomem głównym śladu jego tury. Powiązane elementy ExecuteTool i połączone zasięgi OutputMessages są zagnieżdżone poniżej, a każdy przenosi operation_ParentId = zasięg InvokeAgent z wartością id.
• Rozmowa trwa kilka tur, z których każda jest emitowana jako osobny ślad. Grupuj lub filtruj według gen_ai.conversation.id, aby ponownie połączyć wypowiedzi z jednej rozmowy w jeden wątek.
• Zasięgi OutputMessages nie zawsze emitują element InvokeAgent na poziomie głównym, co oznacza, że mogą (zgodnie z założeniem) dotrzeć bez pasującego elementu nadrzędnego i występować jako autonomiczny ślad składający się z jednego węzła.

Utwórz pakiet eksportu

Stwórz pakiet eksportowy z typem eksportu ustawionym na Copilot Studio, postępując zgodnie z instrukcjami w sekcji Utwórz pakiet eksportowy dokumentacji centrum administracyjnego Power Platform.

Weryfikacja konfiguracji

Po zapisaniu konfiguracji eksportu przeprowadź testową rozmowę z agentem i popewnij, że telemetria dociera do Application Insights. Dostarczanie telemetrii może trwać do 24 godzin w nowych konfiguracjach. Sprawdź, czy:

• W tabeli dependencies pojawiają się zasięgi agentów.
• Zasięgi InvokeAgent, ExecuteTool i OutputMessages każdej tury współdzielą element operation_Id.

Pola Application Insights

Poniższa tabela przedstawia pola w tabeli dependencies oraz wskazuje, które pola są wypełniane dla każdego z trzech eksportowanych zdarzeń agenta: InvokeAgent, ExecuteTool oraz OutputMessages. Semantyka agenta i operacji znajduje się w customDimensions (kluczach gen_ai.* , takich jak gen_ai.operation.name), a nie w natywnych kolumnach.

właściwości customDimensions

Każdy zakres zawiera JSON customDimensions . Poniższa tabela przedstawia typowe klucze występujące w każdym zasięgu:

Klucze dla konkretnych zdarzeń

Poniższa tabela przedstawia klucze specyficzne dla konkretnych zdarzeń:

Odkryj aktualny schemat

Schemat opisany w tym artykule może ewoluować z czasem. Zamiast polegać wyłącznie na wyżej wymienionych tabelach, użyj poniższych zapytań, aby sprawdzić najnowszy schemat na żywo w swoim środowisku.

Wyświetl wbudowane kolumny tabeli

Następujące zapytanie zwraca schemat dependencies na poziomie kolumny tabeli. Użyj go do potwierdzania dostępnych natywnych kolumn podczas tworzenia zapytań, pulpitów czy alertów.

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

Odkryj klucze customDimensions (właściwości dynamiczne)

Poniższe zapytanie wymienia każdy klucz wewnątrz customDimensions JSON w dependencies tabeli: nazwę właściwości, zdarzenia agenta, na których się pojawia (InvokeAgent, ExecuteTool, ), OutputMessagesoraz wartość próby. W przeciwieństwie do natywnego schematu kolumnowego, te właściwości są dynamiczne, więc zapytanie pozostaje dokładne, gdy SDK dodaje nowe gen_ai.* lub inne klucze. Użyj go jako żywego źródła prawdy dla dostępnych atrybutów.

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

Monitoruj eksportowaną telemetrię

Użyj Application Insights Logs, aby zapytać o aktywność agenta i zbadać wykonanie agenta lub narzędzia. Wszystkie eksportowane dane telemetryczne trafiają do tabeli dependencies jako zasięgi:

• Każdy tura agenta to ślad grupowany według udostępnionego elementu operation_Id.
• Zasięg InvokeAgent to poziom główny śladu; zasięgi ExecuteTool i OutputMessages są zagnieżdżone pod nim za pośrednictwem wartości operation_ParentId.
• Grupuj według elementu gen_ai.conversation.id, aby połączyć wiele tur tej samej konwersacji w jeden wątek, i podziel ten identyfikator według elementu _, aby uwzględnić ślady agenta podrzędnego.

Bloki Agenty (wersja zapoznawcza)

Oprócz logów, Application Insights oferuje wbudowane widoki agentów (podgląd ), które wizualizują wyeksportowaną telemetrię GenAI bez konieczności zapisywania zapytań Kusto. Gdy program Copilot Studio zapisuje zasięgi w tabeli dependencies, bloki te odczytują bezpośrednio z tych danych:

• Przebiegi agenta: powoduje wyświetlenie wywołań agenta utworzonych na podstawie zasięgów InvokeAgent, wraz z czasem ich trwania, stanem powodzenia oraz informacją, do której konwersacji należy dany przebieg. Obowiązują pewne ograniczenia; Dowiedz się więcej w Znane ograniczenia i kwestie do rozważenia.
• Narzędzia: agreguje zasięgi ExecuteTool, aby pokazać, z których narzędzi korzystają agenty, jak często oraz jakie wyniki osiągają.
• Modele: Podsumowuje wykorzystanie modelu w różnych przebiegach, ukazując wywołane modele oraz ich wzorce wywołań.

Analizuj telemetrię agentów za pomocą Application Insights

Po połączeniu środowiska z Application Insights rejestruje on dane telemetryczne agentów, gdy użytkownicy wchodzą w interakcje z agentem, także podczas testów w Copilot Studio. Aby zobaczyć zarejestrowane dane telemetryczne, przejdź do sekcji Logi w swoim zasobu Application Insights w Azure. Tutaj możesz używać zapytań Kusto do zapytań i analizy swoich danych. Dowiedz się więcej w przykładowych zapytaniach.

Przykłady zapytań

Poniższe przykłady zapytań Kusto rekonstruują rozmowy agentów Copilot Studio na podstawie tabeli dependencies w Application Insights. Ponieważ w każdej turze każdy zasięg udostępnia ślad operation_Id, zapytania porządkują zasięgi od poziomu głównego (zasięg InvokeAgent przed zasięgami podrzędnymi) w obrębie każdego śladu.

Zapytanie 1. Zwróć pełny ślad dla wybranego identyfikatora konwersacji

To zapytanie zwraca wszystkie zasięgi dla pojedynczej znanej rozmowy, uporządkowane chronologicznie tak, aby każdy zasięg główny jest wymieniony przed zasięgami podrzędnymi. Zastąp symbol zastępczy identyfikator rozmowy identyfikatorem rozmowy swojego agenta. Możesz go znaleźć, wpisując następujące polecenie podczas testowania własnego agenta: /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

Zapytanie 2: Opowiedz o najnowszej rozmowie o konkretnym agentzie

To zapytanie wyszukuje najnowszą rozmowę dla wskazanego agenta w określonym oknie czasowym. Zwraca wszystkie zasięgi dla tej rozmowy w tej samej kolejności chronologicznej, zaczynając od poziomu głównego. Zastąp symbol zastępczy Agent name imieniem agenta.

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

Zapytanie 3: Rozwiń znane właściwości genAI OpenTelemetry do kolumn

To zapytanie zwraca ten sam ślad co zapytanie 2, ale również analizuje każdy znany klucz konwencji semantycznej OpenTelemetry na własną nazwaną kolumnę. Efektem jest płaska, wyraźnie zdefiniowana tabela, w której możesz bezpośrednio sortować, filtrować i skanować generatywne pola AI, takie jak nazwa narzędzia, model, prompt użytkownika, odpowiedź agenta czy identyfikator konwersacji. Zastąp symbol zastępczy Agent name imieniem agenta.

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

Zapytanie 4: Dynamicznie rozwiń wszystkie właściwości genAI OpenTelemetry

To zapytanie zwraca te same zakresy co zapytanie 3, ale każdy klucz gen_ai.* jest dynamicznie rozpakowywany z customDimensions do osobnej kolumny z prefiksem ga_. Ponieważ projekcja jest dynamiczna, każdy nowy gen_ai.* atrybut generowany przez SDK pojawia się automatycznie, bez zmiany zapytania. Zastąp symbol zastępczy Agent name imieniem agenta.

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

Zapytanie 5. Zwróć najnowszą konwersację dla agenta głównego ze wszystkimi jego elementami podrzędnymi, w tym agentami podrzędnymi

To zapytanie zwraca najnowszą konwersację dla nazwanego agenta. Zwraca wszystkie zasięgi dla tej konwersacji oraz dla wszystkich agentów podrzędnych pierwszego poziomu, których ta konwersacja wywołała. Gdy agent wywołuje innego agenta jako narzędzie, agent podrzędny dziedziczy identyfikator konwersacji agenta nadrzędnego z sufiksem _<subConversationId>. Całe drzewo jest odtwarzane przez dopasowanie do identyfikatora najwyższego poziomu. Zastąp symbol zastępczy Agent name imieniem agenta.

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

Znane ograniczenia i kwestie do rozważenia

• Wartość duration nie jest dostępna dla śladów agentów zasilanych standardową wiązką.
• Błędy wykonywania agentów i narzędzi nie są obecnie poprawnie odzwierciedlane w stanach śladów.
• W zależności od wymagań dotyczących rezydencji danych, możesz chcieć korzystać z dedykowanych zasobów Application Insights dla każdego regionu środowiska.
• Zasięgi agentów podrzędnych obecnie mają jako element nadrzędny zasięg InvokeAgent, który wywołał agenta, zamiast zasięgu InvokeAgent wewnątrz własnego śladu.
• Identyfikatory śladów i zasięgów są obecnie emitowane jako identyfikatory GUID (w razie potrzeby z prefiksem), a nie jako dopasowane i w pełni zgodne ze standardem OpenTelemetry 32-znakowe identyfikatory szesnastkowe i 16-znakowe identyfikatory szesnastkowe zasięgu.
• Upewnij się, że lokalne uwierzytelnianie jest włączone na docelowym zasobie Application Insights.
• Eksport telemetrii nie jest transakcyjny. Podczas przejściowych zdarzeń usługowych mogą wystąpić niewielkie straty danych.
• Niespójności danych mogą wystąpić podczas wdrażania aktualizacji importu danych związanych ze schematem.
• Zdarzenia związane z tematem, takie jak TopicStart, TopicAction, i TopicEnd nie są rejestrowane telemetrią na poziomie środowiskowym.
• Aby uprościć raportowanie i rozwiązywanie problemów, unikaj wysyłania telemetrii na poziomie agenta i środowiska do tej samej instancji Application Insights.
• Dane telemetryczne generowane dla agentów utworzonych jako agentów obsługiwanych przez środowisko uruchomieniowe GitHub Copilot mogą różnić się od danych telemetrycznych dla agentów utworzonych jako obsługiwanych przez standardowe środowisko uruchomieniowe.

Informacje pokrewne

• Przegląd telemetrii z Application Insights
• Telemetria na poziomie agenta z Application Insights
• Eksport danych do Application Insights
• aplikacja systemu Azure Insights