Telemetrie auf Umgebungsebene mit Application Insights (Vorschau)

[Dieser Artikel ist eine Vorabdokumentation und kann geändert werden.]

Verwenden Sie Azure-Anwendung Insights, um Copilot Studio-Agenten-Traces zu überwachen, die aus einer verwalteten Umgebung exportiert werden. Nachdem Sie den Export konfiguriert haben, verwenden Sie Azure Monitor und Application Insights, um Agentenläufe zu validieren, die Ausführung von Knoten und Tools zu überwachen, Warnungen zu erstellen und benutzerdefinierte Abfragen sowie Dashboards für die operative Analyse zu erstellen.

Dieser Artikel erklärt, wie man den Export von Copilot Studio-Agenten-Traces auf Umgebungsebene zu Azure-Anwendung Insights über das Power Platform Admin Center konfiguriert.

Voraussetzungen

Bevor Sie die Datenexportverbindung einrichten, erfüllen Sie die Voraussetzungen für den Datenexport in Application Insights.

Was exportiert wird

Wenn Sie den Export aktivieren, wird die Copilot Studio-Agenten-Trace-Telemetrie in Application Insights in einem trace-orientierten, OpenTelemetry-orientierten Observabilitätsformat geschrieben, das Untersuchungen, Dashboards und Benachrichtigungen unterstützt.

Die Agentenereignisse von Copilot Studio werden als Spans in die Tabelle dependencies geschrieben. Jedes exportierte Ereignis (InvokeAgent, ExecuteTool und OutputMessages) ist eine einzelne Span-Zeile (itemType = dependency).

Wie Spans eine Spur bilden

Die Telemetrie folgt dem OpenTelemetry-Trace-and-Span-Modell, das anhand der Spalten operation_Id und operation_ParentId rekonstruiert wird:

• Jeder Agenten-Turn ist ein eigener Trace, der durch eine gemeinsame operation_Id identifiziert wird, wodurch Application Insights den Turn gruppieren und in der End-to-End-Transaktionsansicht darstellen kann.
• Die Spannweite InvokeAgent ist die Wurzel der Spur ihrer Kurve. Seine ExecuteTool und die verbundenen OutputMessages-Spannen sind darunter verschachtelt, wobei jede operation_ParentId = das InvokeAgent der id-Spanne trägt.
• Ein Gespräch erstreckt sich über mehrere Runden, jede als eigene Spur ausgestrahlt. Nach gen_ai.conversation.id gruppieren oder filtern, um die Beiträge einer Unterhaltung wieder zusammenzuführen.
• Subagenten werden als eigener Trace ausgeführt. Wenn ein Agent einen anderen Agenten als Werkzeug aufruft, übernimmt der Sub-Agent die Konversations-ID des übergeordneten Agenten mit dem Suffix _<subConversationId>, z. B. <rootConversationId>_<subConversationId>. Teilen Sie gen_ai.conversation.id anhand von _ auf und gleichen Sie anhand des Stammteils ab, um den vollständigen Multi-Agenten-Baum zu rekonstruieren (weitere Informationen finden Sie in Abfrage 5).
• OutputMessages spans erzeugen nicht immer einen InvokeAgent-Root, was bedeutet, dass sie absichtlich ohne zugehöriges übergeordnetes Element ankommen und als eigenständiger Trace mit nur einem Knoten erscheinen können.

Exportpaket erstellen

Erstellen Sie ein Exportpaket, bei dem der Exporttyp auf Copilot Studio festgelegt ist, indem Sie die Anweisungen in Create an export package in der Dokumentation zum Power Platform Admin Center befolgen.

Überprüfen der Konfiguration

Nachdem Sie die Exportkonfiguration gespeichert haben, führen Sie eine Testkonversation mit dem Agenten durch und bestätigen, dass die Telemetrie in Application Insights eintrifft. Die Telemetriezustellung kann bei neuen Konfigurationen bis zu 24 Stunden dauern. Überprüfen Sie das:

• Agentenspannweiten erscheinen in der dependencies Tabelle.
• Die InvokeAgent-, ExecuteTool- und OutputMessages-Spannen jeder Runde teilen sich ein operation_Id.

Anwendungs-Insights-Felder

Die folgende Tabelle zeigt die Felder in der Tabelle dependencies und welche Felder für jedes der drei exportierten Agentenereignisse ausgefüllt sind: InvokeAgent, ExecuteTool, und OutputMessages. Agenten- und Operationssemantik befinden sich in customDimensions (den gen_ai.* Schlüsseln, wie z. B gen_ai.operation.name. ), nicht in den nativen Spalten.

Eigenschaften von customDimensions

Jeder Span enthält das customDimensions-JSON. Die folgende Tabelle zeigt gängige Schlüssel, die auf jeder Spanne erscheinen:

Ereignisspezifische Schlüssel

Die folgende Tabelle zeigt die ereignisspezifischen Schlüssel:

Entdecken Sie das aktuelle Schema

Das in diesem Artikel dokumentierte Schema könnte sich im Laufe der Zeit weiterentwickeln. Anstatt sich ausschließlich auf die oben genannten Tabellen zu verlassen, verwenden Sie die folgenden Abfragen, um das neueste Schema live in Ihrer Umgebung zu inspizieren.

Systemeigene Tabellenspalten auflisten

Die folgende Abfrage liefert das Schema der dependencies Tabelle auf Spaltenebene. Nutzen Sie es, um verfügbare native Spalten beim Erstellen von Abfragen, Dashboards oder Benachrichtigungen zu bestätigen.

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

Entdecke benutzerdefinierte Dimensions-Schlüssel (dynamische Eigenschaften)

Die folgende Abfrage listet alle Schlüssel im JSON-Feld customDimensions in der Tabelle dependencies auf: den Eigenschaftsnamen, in welchen Agentenereignissen sie vorkommen (InvokeAgent, ExecuteTool, OutputMessages), und einen Beispielwert. Im Gegensatz zum nativen Spaltenschema sind diese Eigenschaften dynamisch, sodass diese Abfrage korrekt bleibt, wenn das SDK neue gen_ai.* oder andere Schlüssel ergänzt. Nutze es als lebendige Quelle der Wahrheit für verfügbare Attribute.

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

Überwachen Sie exportierte Telemetrie

Verwenden Sie die Application Insights Logs, um die Aktivitäten von Agenten abzufragen und die Ausführung von Agenten oder Tools zu untersuchen. Alle exportierten Telemetriedaten werden als Spans in der Tabelle dependencies gespeichert:

• Jeder Turn eines Agenten ist ein Trace, gruppiert anhand eines gemeinsamen operation_Id.
• Die Spannweite InvokeAgent ist die Spurwurzel; ExecuteTool und OutputMessages spannt darunter ein Nest durch operation_ParentId.
• Gruppieren Sie nach gen_ai.conversation.id, um mehrere Runden derselben Konversation in einem Thread zusammenzufassen, und teilen Sie diese ID bei _, um Sub-Agent-Traces einzubeziehen.

Agents (Vorschau)-Blades

Zusätzlich zu Logs bietet Application Insights integrierte Agents-(Vorschau-) Ansichten, die die exportierte GenAI-Telemetrie visualisieren, ohne Kusto-Abfragen zu schreiben. Während Copilot Studio seine Spans auf die dependencies Tabelle schreibt, lesen diese Blades direkt aus diesen Daten:

• Agent-Ausführungen: Listet Agent-Aufrufe auf, die aus den Spans InvokeAgent erstellt wurden, einschließlich Dauer, Erfolgsstatus und der Konversation, zu der die jeweilige Ausführung gehört. Es gelten einige Einschränkungen; Erfahren Sie mehr unter Bekannte Einschränkungen und Überlegungen.
• Tools: Aggregiert die ExecuteTool Spannen, um zu zeigen, welche Tools die Agenten anrufen, wie oft und wie sie arbeiten.
• Modelle: Fasst die Modellnutzung über verschiedene Durchläufe hinweg zusammen, zeigt die aufgerufenen Modelle und deren Aufrufmuster.

Agententelemetrie mit Application Insights analysieren

Nachdem Sie Ihre Umgebung mit Application Insights verbunden haben, protokolliert sie die Telemetriedaten der Agenten, wenn Nutzer mit dem Agenten interagieren, einschließlich Tests im Copilot Studio. Um die protokollierten Telemetriedaten einzusehen, gehen Sie zum Abschnitt Logs Ihrer Application Insights-Ressource in Azure. Hier können Sie Kusto-Abfragen verwenden, um Ihre Daten abzufragen und zu analysieren. Erfahren Sie mehr in Beispielfragen.

Beispielabfragen

Die folgenden Beispiele für Kusto-Abfragen rekonstruieren Copilot Studio-Agentengespräche aus der dependencies Tabelle in Application Insights. Da jeder Span pro Durchlauf ein Trace operation_Id gemeinsam nutzt, ordnen die Abfragen die Spans innerhalb jedes Trace in Wurzel-zuerst-Reihenfolge an (der InvokeAgent Span vor seinen untergeordneten Spans).

Abfrage 1: Geben Sie eine vollständige Verfolgung für eine bestimmte Konversations-ID zurück

Diese Abfrage gibt alle Spans für eine bekannte Konversation zurück, chronologisch geordnet, wobei jeder Root-Span vor seinen Child-Spans aufgeführt wird. Ersetzen Sie den Platzhalter Conversation ID durch die Konversations-ID Ihres Agenten. Sie finden ihn, indem Sie beim Testen Ihres benutzerdefinierten Agenten den folgenden Befehl eingeben: /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

Abfrage 2: Gibt die letzte Konversation für einen bestimmten Agenten zurück

Diese Abfrage findet die aktuellste Konversation für einen benannten Agenten innerhalb des angegebenen Zeitfensters. Jede Zeile für dieses Gespräch wird in derselben chronologischen, Wurzel-zuerst-Reihenfolge zurückgegeben. Ersetzen Sie den Namensplatzhalter des Agenten durch den Namen Ihres Agenten.

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

Abfrage 3: Bekannte genAI-OpenTelemetry-Eigenschaften zu Spalten erweitern

Diese Abfrage gibt denselben Trace wie Abfrage 2 zurück, zerlegt aber auch jeden bekannten Schlüssel der OpenTelemetry-Semantikkonventionen in eine eigene benannte Spalte. Das Ergebnis ist eine flache, explizit definierte Tabelle, in der Sie die generativen KI-Felder wie Werkzeugname, Modell, Benutzerprompt, Agentenantwort und Konversations-ID direkt sortieren, filtern und scannen können. Ersetzen Sie den Namensplatzhalter des Agenten durch den Namen Ihres Agenten.

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

Abfrage 4: Erweitern Sie alle genAI OpenTelemetrie-Eigenschaften dynamisch

Diese Abfrage liefert dieselben Bereiche wie Abfrage 3, aber jeder gen_ai.*-Schlüssel wird dynamisch aus customDimensions in eine eigene mit ga_ präfixierte Spalte entpackt. Da die Projektion dynamisch ist, erscheint jedes neue gen_ai.* Attribut, das das SDK später ausgibt, automatisch, ohne die Abfrage zu ändern. Ersetzen Sie den Namensplatzhalter des Agenten durch den Namen Ihres Agenten.

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

Abfrage 5: Die neueste Konversation für einen Root-Agenten mit all seinen untergeordneten Agenten einschließlich Sub-Agenten zurückgeben

Diese Abfrage liefert das aktuellste Gespräch für einen benannten Agenten. Er gibt jede Spanne für dieses Gespräch und für alle von ihm aufgerufenen Erstebene-Subagenten zurück. Wenn ein Agent einen anderen Agenten als Werkzeug aufruft, übernimmt der Unteragent die Konversations-ID des übergeordneten Agenten mit dem Suffix _<subConversationId>. Der gesamte Baum wird durch Abgleich anhand der ID der obersten Ebene rekonstruiert. Ersetzen Sie den Namensplatzhalter des Agenten durch den Namen Ihres Agenten.

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

Bekannte Einschränkungen und Überlegungen

• Der duration Wert ist für klassische Agenten-Traces nicht verfügbar.
• Fehler bei der Ausführung von Agenten und Tools werden derzeit nicht korrekt in den Trace-Status dargestellt.
• Je nach Ihren Anforderungen an die Datenresidenz sollten Sie für jede Umgebungsregion dedizierte Application Insights-Ressourcen verwenden.
• Sub-Agent-Spans sind derzeit dem InvokeAgent-Span, der den Agenten aufgerufen hat, als Parent zugeordnet, anstatt dem InvokeAgent-Span innerhalb ihres eigenen Trace.
• Trace- und Span-IDs werden derzeit als GUIDs ausgegeben (mit Präfix, wo erforderlich), anstatt vollständig dem OpenTelemetry-Standard entsprechender 32-stelliger hexadezimaler Trace-IDs bzw. 16-stelliger hexadezimaler Span-IDs.
• Stellen Sie sicher, dass die lokale Authentifizierung auf der Zielressource Application Insights aktiviert ist.
• Telemetrie-Export ist nicht transaktional. Während transienter Serviceereignisse können kleine Datenverluste auftreten.
• Dateninkonsistenzen können auftreten, wenn schemabezogene Ingestion-Updates ausgerollt werden.
• Themenbezogene Ereignisse wie TopicStart, TopicAction, und TopicEnd werden nicht mit der Telemetrie auf Umweltebene erfasst.
• Um Berichterstattung und Fehlerbehebung zu vereinfachen, sollten Sie vermeiden, sowohl Agenten- als auch Umwelttelemetrie an dieselbe Application Insights-Instanz zu senden.
• Die für Agenten generierte Telemetrie, die in der neuen Agentenerfahrung erstellt wurden, könnte sich von der Telemetrie für Agenten unterscheiden, die in der klassischen Agentenerstellungsumgebung erstellt wurden.

Verwandte Informationen

• Übersicht über die Telemetrie mit Application Insights
• Telemetrie auf Agentenebene mit Application Insights
• Daten zu Application Insights exportieren
• Azure-Anwendung Insights