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.

Prerequisites

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

Znane ograniczenia i kwestie do rozważenia

• Ta funkcja nie obsługuje scenariuszy z konfiguracją agenta nieuwierzytelnionego ani konfiguracją agenta w środowisku wielodzierżawnym. Dlatego Application Insights ich nie rejestruje.
• Funkcja ta jest obecnie dostępna tylko w środowiskach chmury publicznej Microsoft.
• W niektórych scenariuszach dotyczących połączonych agentów relacja rodzic-dziecko między śladami nie jest poprawnie mapowana.
• Wartość duration nie jest dostępna dla śladów agentów obsługiwanych przez standardowe środowisko uruchomieniowe.
• Upewnij się, że w docelowym zasobie usługi Application Insights jest włączona właściwość Uwierzytelnianie lokalne.
• Eksport telemetrii nie jest transakcyjny. Podczas przejściowych zdarzeń usługowych mogą wystąpić niewielkie straty danych.
• Niespójności danych mogą wystąpić w miarę wdrażania aktualizacji pozyskiwania danych związanych ze schematem.
• Ta cecha nie rejestruje zdarzeń związanych z tematem, takich jak TopicStart, TopicAction, i TopicEnd.
• Identyfikatory śledzenia i zakresu obecnie wykorzystują reprezentację opartą na GUID zamiast standardowego 32-znakowego identyfikatora śledzenia OpenTelemetry i 16-znakowego sześciastkowego identyfikatora rozciągu.
• Aby uprościć raportowanie i rozwiązywanie problemów, unikaj wysyłania telemetrii na poziomie agenta i środowiska do tej samej instancji Application Insights.
• Telemetria może się różnić między agentami zasilanymi przez wiązkę GitHub Copilot a agentami zasilanymi standardową wiązką.
• Upewnij się, że konfiguracja Application Insights na poziomie środowiskowym spełnia wymagania dotyczące rezydencji danych, prywatności oraz kontroli dostępu opartej na rolach (RBAC).
• Duża treść logów, w tym odpowiedzi agentów i argumenty narzędzi, może być skracana.

Informacje pokrewne

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