Télémétrie au niveau de l’environnement avec Application Insights (aperçu)

[Cet article fait partie de la documentation en version préliminaire et peut faire l’objet de modifications.]

Utilisez Azure Application Insights pour surveiller les traces des agents Copilot Studio exportées à partir d’un environnement géré. Après avoir configuré l’exportation, utilisez Azure Monitor et Application Insights pour valider les exécutions d’agents, surveiller l’exécution des nœuds et des outils, créer des alertes et créer des requêtes et tableaux de bord personnalisés pour l’analyse opérationnelle.

Cet article explique comment configurer l’exportation au niveau de l’environnement des traces d’agents Copilot Studio vers Azure Application Insights via le centre d’administration Power Platform.

Prerequisites

Avant de configurer la connexion d’exportation de données, remplissez les prérequis d’Exporter les données vers Application Insights.

Éléments exportés

Lorsque vous activez l’exportation, la télémétrie des traces de l’agent Copilot Studio est consignée dans Application Insights dans un format d’observabilité orienté traces, aligné sur OpenTelemetry, qui prend en charge l’analyse, les tableaux de bord et les alertes.

Les événements d’agent de Copilot Studio sont consignés dans la table dependencies sous forme de spans. Chaque événement exporté (InvokeAgent, ExecuteTool et OutputMessages) correspond à une seule ligne de segment (itemType = dependency).

Comment les spans constituent une trace

La télémétrie suit le modèle de trace et de portée OpenTelemetry, reconstruit à travers les operation_Id colonnes et operation_ParentId :

• Chaque tour d’assistant est sa propre trace, identifiée par un operation_Id partagé, ce qui permet à Application Insights de regrouper ce tour et de l’afficher dans la vue des transactions de bout en bout.
• Le span InvokeAgent correspond à la racine de la trace de son tour. Son ExecuteTool et ses spans OutputMessages connectés s’imbriquent en-dessous, chacun portant operation_ParentId = l’InvokeAgent de l’id du span.
• Une conversation comporte plusieurs échanges, chacun étant émis sous la forme d’une trace distincte. Regrouper ou filtrer par gen_ai.conversation.id pour regrouper les messages d’une même conversation.
• OutputMessages Les spans n’émettent pas toujours une InvokeAgent racine, ce qui signifie qu’ils peuvent (par conception) arriver sans parent correspondant et apparaître comme une trace autonome à nœud unique.

Créer un package d’exportation

Créez un paquet d’exportation avec le type d’exportation défini sur Copilot Studio en suivant les instructions dans Créer un paquet d’exportation de la documentation du centre d’administration Power Platform.

Valider la configuration

Après avoir enregistré la configuration d’exportation, lancez une conversation de test avec l’agent et confirmez que la télémétrie arrive dans Application Insights. La livraison de la télémétrie peut prendre jusqu’à 24 heures sur les nouvelles configurations. Vérifiez que :

• Les spans d’assistant apparaissent dans la table dependencies.
• À chaque tour, les segments InvokeAgent, ExecuteTool et OutputMessages partagent un operation_Id.

Champs Application Insights

Le tableau suivant montre les champs du dependencies tableau, et quels champs sont remplis pour chacun des trois événements d’agent exportés : InvokeAgent, ExecuteTool, et OutputMessages. La sémantique de l’agent et de l’opération est dans customDimensions (les gen_ai.* clés, comme gen_ai.operation.name), et non dans les colonnes natives.

Propriétés des dimensions personnalisées

Chaque span contient le JSON customDimensions. Le tableau suivant présente les clés communes qui apparaissent dans chaque span :

Clés spécifiques à l’événement

Le tableau suivant présente les clés spécifiques à chaque événement :

Découvrez le schéma actuel

Le schéma documenté dans cet article pourrait évoluer au fil du temps. Plutôt que de vous fier uniquement aux tableaux mentionnés précédemment, utilisez les requêtes suivantes pour inspecter le dernier schéma en ligne dans votre propre environnement.

Lister les colonnes de la table native

La requête suivante renvoie le schéma au niveau de la colonne de la dependencies table. Utilisez-le pour confirmer les colonnes natives disponibles lors de la création de requêtes, de tableaux de bord ou d’alertes.

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

Découvrez les clés customDimensions (propriétés dynamiques)

La requête suivante liste toutes les clés du customDimensions JSON dans le dependencies tableau : le nom de la propriété, les événements d’agent sur lesquels elle apparaît (InvokeAgent, ExecuteTool, OutputMessages), et une valeur d’exemple. Contrairement au schéma natif de colonnes, ces propriétés sont dynamiques, donc cette requête reste précise lorsque le SDK ajoute de nouvelles gen_ai.* ou d’autres clés. Utilisez-le comme source vivante de vérité pour les attributs disponibles.

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

Surveiller la télémétrie exportée

Utilisez les journaux d’Application Insights Logs pour interroger l’activité des agents et examiner l’exécution des agents ou des outils. Toute la télémétrie exportée aboutit dans la table dependencies sous forme de spans :

• Chaque tour d’assistant est une trace, regroupée par un operation_Id partagé.
• Le span InvokeAgent correspond à la racine de la trace ; les spans ExecuteTool et OutputMessages s’imbriquent en dessous via operation_ParentId.
• Regroupez par gen_ai.conversation.id pour regrouper dans un même fil plusieurs tours d’une même conversation, et fractionnez cet ID sur _ afin d’inclure des traces de sous-assistants.

Panneaux Assistants (version préliminaire)

En plus de Logs, Application Insights propose des vues intégrées Agents (préversion) qui visualisent la télémétrie GenAI exportée sans avoir à écrire de requêtes Kusto. Au fur et à mesure que Copilot Studio écrit ses spans sur la table dependencies, ces panneaux lisent directement à partir de ces données :

• Exécutions d’agent : répertorie les invocations d’agent créées à partir des InvokeAgent segments, avec leur durée, leur statut de réussite et la conversation à laquelle chaque exécution appartient. Certaines limitations s’appliquent ; en savoir plus dans Limitations et considérations connues.
• Outils : Agrége les ExecuteTool spans pour montrer quels outils les agents appellent, à quelle fréquence et comment ils fonctionnent.
• Modèles : Résume l’utilisation des modèles à travers les exécutions, en mettant en avant les modèles invoqués et leurs schémas d’appel.

Analysez la télémétrie des agents avec Application Insights

Après avoir connecté votre environnement à Application Insights, il enregistre les données de télémétrie de l’agent lorsque les utilisateurs interagissent avec l’agent, y compris lors des tests dans Copilot Studio. Pour consulter les données de télémétrie enregistrées, rendez-vous dans la section Journaux de votre ressource Application Insights sur Azure. Ici, vous pouvez utiliser les requêtes Kusto pour interroger et analyser vos données. En savoir plus dans les requêtes d’exemple.

Exemples de requêtes

Les exemples de requêtes Kusto suivants reconstruisent les conversations des agents de Copilot Studio à partir du dependencies tableau dans Application Insights. Comme chaque span partage une trace operation_Id à chaque tour, les requêtes ordonnent les spans en commençant par le span racine (le span InvokeAgent avant ses spans enfants) au sein de chaque trace.

Requête 1 : Retourner une trace complète pour un identifiant de conversation spécifique

Cette requête renvoie tous les spans d’une conversation donnée, classés par ordre chronologique, chaque span racine apparaissant avant ses spans enfants. Remplacez le Conversation ID par celui de votre agent. Vous pouvez le trouver en entrant la commande suivante lors du test de votre agent personnalisé : /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

Requête 2 : Retournez la dernière conversation pour un agent spécifique

Cette requête trouve la conversation la plus récente pour un agent nommé dans la fenêtre de temps spécifiée. Il retourne chaque intervalle pour cette conversation dans le même ordre chronologique, racine en premier. Remplacez le nom de l’agent par celui de votre 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

Requête 3 : Étendre les propriétés connues de GenAI OpenTelemetry en colonnes

Cette requête renvoie la même trace que la requête 2, mais elle analyse également chaque clé connue de la convention sémantique OpenTelemetry dans sa propre colonne nommée. Le résultat est une table plate et explicitement définie où vous pouvez trier, filtrer et scanner directement les champs génératifs d’IA tels que le nom de l’outil, le modèle, l’invite utilisateur, la réponse de l’agent et l’identifiant de conversation. Remplacez le nom de l’agent par celui de votre 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

Requête 4 : Étendre dynamiquement toutes les propriétés d’OpenTelemetry genAI

Cette requête renvoie les mêmes segments que la requête 3, mais chaque clé gen_ai.* est extraite dynamiquement de customDimensions dans sa propre colonne préfixée par ga_. Comme la projection est dynamique, tout nouvel gen_ai.* attribut émis ultérieurement par le SDK apparaît automatiquement sans modifier la requête. Remplacez le nom de l’agent par celui de votre 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_')

Requête 5 : Retourner la dernière conversation pour un assistant racine avec tous ses enfants, y compris les sous-assistants

Cette requête renvoie la conversation la plus récente pour un assistant nommé. Il renvoie chaque intervalle pour cette conversation et pour tous les sous-assistants de premier niveau qu’il a invoqués. Lorsqu’un agent appelle un autre agent en tant qu’outil, le sous-agent hérite de l’identifiant de conversation du parent avec le suffixe _<subConversationId>. L’arborescence entière est reconstruite par mise en correspondance avec l’ID de niveau supérieur. Remplacez le nom de l’agent par celui de votre 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

Limitations et considérations connues

• La valeur duration n’est pas disponible pour les traces des assistants reposant sur l’environnement d’exécution standard.
• Les erreurs d’exécution des agents et des outils ne sont pas actuellement correctement exprimées dans les statuts des traces.
• En fonction de vos besoins en résidence des données, vous pourriez vouloir utiliser des ressources dédiées à Application Insights pour chaque région d’environnement.
• Les spans de sous-assistant ont actuellement pour parent le span InvokeAgent qui a invoqué l’assistant, au lieu du span InvokeAgent situé dans leur propre trace.
• Les identifiants de trace et de span sont actuellement générés sous forme de GUID (avec un préfixe si nécessaire), au lieu d’être pleinement conformes au standard OpenTelemetry, avec un identifiant de trace de 32 caractères hexadécimaux et un identifiant de span de 16 caractères hexadécimaux.
• Assurez-vous que l’authentification locale est activée sur la ressource cible Application Insights.
• L’export de télémétrie n’est pas transactionnel. Lors d’événements de service transitoires, de petites pertes de données peuvent survenir.
• Des incohérences de données peuvent survenir lors du déploiement des mises à jour d’ingestion liées au schéma.
• Les événements liés au sujet comme TopicStart, TopicAction, et TopicEnd ne sont pas capturés par la télémétrie au niveau de l’environnement.
• Pour simplifier les rapports et le dépannage, évitez d’envoyer à la fois des télémétries au niveau de l’agent et de l’environnement à la même instance d’Application Insights.
• La télémétrie émise pour les assistants créés dans l’expérience de création des assistants reposant sur l’environnement d’exécution GitHub Copilot peut différer de celle des assistants créés dans l’expérience de création des assistants reposant sur l’environnement d’exécution standard.

Informations associées

• Aperçu de la télémétrie avec Application Insights
• Télémétrie au niveau de l’agent avec Application Insights
• Exporter les données vers Application Insights
• Azure Application Insights