Ajouter la télémétrie à votre bot
S'APPLIQUE À : SDK v4
La journalisation des données de télémétrie permet aux applications de bot d’envoyer des données d’événement à des services de télémétrie tels qu’Application Insights. La télémétrie fournit des insights sur votre bot en montrant quelles fonctionnalités sont utilisées le plus, détecte le comportement indésirable et offre une visibilité sur la disponibilité, les performances et l’utilisation.
Cet article explique comment implémenter des données de télémétrie dans votre bot à l’aide d’Application Insights. Cet article couvre les points suivants :
- Code requis pour connecter les données de télémétrie dans votre bot et se connecter à Application Insights.
- Comment activer la télémétrie dans les dialogues de votre bot.
- Comment activer la télémétrie pour capturer des données d’utilisation à partir d’autres services, comme les services Azure AI.
- Comment visualiser vos données de télémétrie dans Application Insights.
Important
Pour un bot régional qui peut collecter des informations d’identification personnelle (PII) dans la télémétrie, votre ressource Application Insights et votre ressource Azure Bot doivent se trouver dans la même région que le bot. Si les ressources se trouvent dans différentes régions, les informations d’identification personnelle peuvent quitter la région géographique du bot.
Prérequis
- L’exemple de code CoreBot
- L’exemple de code d’Application Insights
- Un abonnement à Microsoft Azure
- Une clé Application Insights
- Vous êtes familiarisé à Application Insights
- git
Remarque
L'exemple de code Application Insights a été créé au-dessus de l’exemple de code CoreBot. Cet article vous guide tout au long de la modification de l’exemple de code CoreBot pour incorporer la télémétrie. Si vous suivez dans Visual Studio, vous disposez de l’exemple de code Application Insights au moment où vous avez terminé.
Activer la télémétrie dans votre bot
Cet article commence à partir de l’exemple d’application CoreBot et ajoute le code requis pour intégrer la télémétrie dans n’importe quel bot. Cela permet à Application Insights de commencer à suivre les requêtes.
Important
Si vous n’avez pas configuré votre compte Application Insights et créé votre clé Application Insights, faites-le avant de continuer.
Ajoutez le package NuGet
Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
. Pour plus d’informations sur l’utilisation de NuGet, consultez Installer et gérer des packages dans Visual Studio :Ajoutez les instructions suivantes dans
Startup.cs
:using Microsoft.ApplicationInsights.Extensibility; using Microsoft.Bot.Builder.ApplicationInsights; using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core; using Microsoft.Bot.Builder.Integration.AspNet.Core;
Conseil
Si vous suivez en mettant à jour l’exemple de code CoreBot, vous remarquerez que l’instruction using existe
Microsoft.Bot.Builder.Integration.AspNet.Core
déjà dans l’exemple CoreBot.Ajoutez le code suivant à la méthode
ConfigureServices()
dansStartup.cs
. Cela rendra les services de télémétrie disponibles pour votre robot via l’injection de dépendances (DI) :// This method gets called by the runtime. Use this method to add services to the container. public void ConfigureServices(IServiceCollection services) { ... // Create the Bot Framework Adapter with error handling enabled. services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); // Add Application Insights services into service collection services.AddApplicationInsightsTelemetry(); // Create the telemetry client. services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>(); // Add telemetry initializer that will set the correlation context for all telemetry items. services.AddSingleton<ITelemetryInitializer, OperationCorrelationTelemetryInitializer>(); // Add telemetry initializer that sets the user ID and session ID (in addition to other bot-specific properties such as activity ID) services.AddSingleton<ITelemetryInitializer, TelemetryBotIdInitializer>(); // Create the telemetry middleware to initialize telemetry gathering services.AddSingleton<TelemetryInitializerMiddleware>(); // Create the telemetry middleware (used by the telemetry initializer) to track conversation events services.AddSingleton<TelemetryLoggerMiddleware>(); ... }
Conseil
Si vous suivez la procédure en mettant à jour l’exemple de code CoreBot, vous remarquerez qu’il
services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();
existe déjà.Demandez à l’adaptateur d’utiliser le code de l’intergiciel qui a été ajouté à la méthode
ConfigureServices()
. Pour ceAdapterWithErrorHandler.cs
faire, utilisez le paramètre TelemetryInitializerMiddleware telemetryInitializerMiddleware dans la liste des paramètres du constructeur et l’instructionUse(telemetryInitializerMiddleware);
dans le constructeur, comme illustré ici :public AdapterWithErrorHandler(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger, TelemetryInitializerMiddleware telemetryInitializerMiddleware, ConversationState conversationState = null) : base(configuration, logger) { ... Use(telemetryInitializerMiddleware); }
Vous devez également ajouter
Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
à votre liste d’instructions using dansAdapterWithErrorHandler.cs
.Ajoutez la clé d’instrumentation Application Insights à votre fichier
appsettings.json
. Leappsettings.json
fichier contient des métadonnées sur les services externes que le bot utilise lors de l’exécution. Par exemple, La connexion et les métadonnées des services Cosmos DB, Application Insights et Azure AI y sont stockées. L’ajout à votre fichierappsettings.json
doit être au format suivant :{ "MicrosoftAppId": "", "MicrosoftAppPassword": "", "ApplicationInsights": { "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } }
Remarque
Pour plus d’informations sur l’obtention de la clé d’instrumentation Application Insights, consultez l’article clés Application Insights.
À ce stade, le travail préliminaire pour activer la télémétrie à l’aide d’Application Insights est effectué. Vous pouvez exécuter votre bot localement à l’aide de l’émulateur, puis accéder à Application Insights pour voir ce qui est journalisé, tel que le temps de réponse, l’intégrité globale de l’application et les informations d’exécution générales.
Activer la télémétrie dans les dialogues de votre bot
Lorsque vous ajoutez un nouveau dialogue à ComponentDialog, celui-ci hérite de Microsoft.Bot.Builder.IBotTelemetryClient pour son dialogue parent. Par exemple, dans l’exemple d’application CoreBot, toutes les boîtes de dialogue sont ajoutées à MainDialog, qui est un ComponentDialog. Une fois que vous avez défini la propriété TelemetryClient sur MainDialog, toutes les boîtes de dialogue ajoutées à celui-ci héritent automatiquement de telemetryClient. Il n’est donc pas nécessaire de définir explicitement les dialogues lors de l’ajout de dialogues.
Suivez les étapes ci-dessous pour mettre à jour votre exemple de CoreBot :
Dans
MainDialog.cs
, mettez à jour la liste des paramètres de constructeur afin d'inclure le paramètreIBotTelemetryClient
, puis définissez la propriété TelemetryClient de MainDialog sur cette valeur comme indiqué dans l’extrait de code suivant :public MainDialog(IConfiguration configuration, ILogger<MainDialog> logger, IBotTelemetryClient telemetryClient) : base(nameof(MainDialog)) { // Set the telemetry client for this and all child dialogs. this.TelemetryClient = telemetryClient; ... }
Conseil
Si vous suivez et mettez à jour l’exemple de code CoreBot, vous pouvez faire référence à l’exemple de code Application Insights si vous rencontrez des problèmes.
La télémétrie est désormais ajoutée à vos dialogues de bot. Si vous exécutez votre bot maintenant, vous devez voir les éléments connectés dans Application Insights ; Toutefois, si vous disposez d’une technologie intégrée telle qu’un service Azure AI, vous devez également ajouter le TelemetryClient
code à ce code.
Activer ou désactiver l’événement d’activité et la journalisation des informations personnelles
Activer ou désactiver la journalisation des activités
Par défaut, TelemetryInitializerMiddleware
utilise TelemetryLoggerMiddleware
pour journaliser les données de télémétrie quand votre bot envoie/reçoit des activités. La journalisation des activités crée des journaux d’événements personnalisés dans votre ressource Application Insights. Si vous le souhaitez, vous pouvez désactiver la journalisation des événements d’activité en définissant la valeur logActivityTelemetry
false sur la valeur false lors de l’inscription TelemetryInitializerMiddleware
dans Startup.cs.
public void ConfigureServices(IServiceCollection services)
{
...
// Add the telemetry initializer middleware
services.AddSingleton<TelemetryInitializerMiddleware>(sp =>
{
var loggerMiddleware = sp.GetService<TelemetryLoggerMiddleware>();
return new TelemetryInitializerMiddleware(loggerMiddleware, logActivityTelemetry: false);
});
...
}
Activer ou désactiver la journalisation des informations personnelles
Par défaut, si la journalisation des activités est activée, certaines propriétés sur les activités entrantes/sortantes sont exclues de la journalisation, car elles sont susceptibles de contenir des informations personnelles, telles que le nom d’utilisateur et le texte de l’activité. Vous pouvez choisir d’inclure ces propriétés dans votre journalisation en apportant la modification suivante à Startup.cs au moment d’inscrire TelemetryLoggerMiddleware
.
public void ConfigureServices(IServiceCollection services)
{
...
// Add the telemetry initializer middleware
services.AddSingleton<TelemetryLoggerMiddleware>(sp =>
{
var telemetryClient = sp.GetService<IBotTelemetryClient>();
return new TelemetryLoggerMiddleware(telemetryClient, logPersonalInformation: true);
});
...
}
Ensuite, nous verrons ce qui doit être inclus pour ajouter des fonctionnalités de télémétrie aux dialogues. Cela vous permettra d’obtenir des informations supplémentaires, telles que ce qui est exécuté par les boîtes de dialogue et les statistiques sur chacune d’elles.
Activation de la télémétrie pour capturer les données d'utilisation d'autres services, comme LUIS et QnA Maker
Remarque
Azure AI QnA Maker sera mis hors service le 31 mars 2025. À partir du 1er octobre 2022, vous ne pourrez plus créer de nouvelles ressources ou bases de connaissances QnA Maker. Une version plus récente de la fonctionnalité de questions et réponses est désormais disponible dans le cadre d’Azure AI Language.
La réponse aux questions personnalisées, une fonctionnalité d'Azure AI Language, est la version mise à jour du service QnA Maker. Pour plus d’informations sur la prise en charge des questions et réponses dans le kit de développement logiciel (SDK) Bot Framework, reportez-vous à Compréhension du langage naturel.
Remarque
Compréhension du langage (LUIS) sera mis hors service le 1er octobre 2025. À compter du 1er avril 2023, vous ne pourrez pas créer de nouvelles ressources LUIS. Une version plus récente de Compréhension du langage est désormais disponible dans le cadre d'Azure AI Language.
Compréhension du langage courant (CLU), une fonctionnalité d’Azure AI Language, est la version mise à jour de LUIS. Pour en savoir plus sur la prise en charge de la compréhension du langage dans le Kit de développement logiciel (SDK) Bot Framework, reportez-vous à Compréhension du langage naturel.
Nous allons ensuite implémenter la fonctionnalité de télémétrie dans votre service LUIS. Le service LUIS dispose d’une journalisation de télémétrie intégrée disponible. Il est donc peu nécessaire de commencer à obtenir des données de télémétrie à partir de LUIS. Si vous souhaitez activer la télémétrie dans un bot QnA Maker activé, consultez Ajouter des données de télémétrie à votre bot QnA Maker
Le paramètre
IBotTelemetryClient telemetryClient
est obligatoire dans le constructeurFlightBookingRecognizer
deFlightBookingRecognizer.cs
:public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
Ensuite, activez le
telemetryClient
moment où vous créez votreFlightBookingRecognizer
LuisRecognizer
constructeur. Pour ce faire, ajoutez-letelemetryClient
en tant que nouveau LuisRecognizerOption :if (luisIsConfigured) { var luisApplication = new LuisApplication( configuration["LuisAppId"], configuration["LuisAPIKey"], "https://" + configuration["LuisAPIHostName"]); // Set the recognizer options depending on which endpoint version you want to use. var recognizerOptions = new LuisRecognizerOptionsV3(luisApplication) { TelemetryClient = telemetryClient, }; _recognizer = new LuisRecognizer(recognizerOptions); }
Et voilà ! Vous disposez d’un robot fonctionnel qui enregistre les données de télémétrie dans Application Insights. Vous pouvez utiliser Bot Framework Emulator pour exécuter votre robot localement. Vous ne devriez pas voir les modifications apportées au comportement du robot, mais les informations de journalisation seront enregistrées dans Application Insights. Interagissez avec le bot en envoyant plusieurs messages et dans la section suivante, nous examinerons les résultats de télémétrie dans Application Insights.
Pour plus d’informations sur le test et le débogage de votre robot, vous pouvez consulter les articles suivants :
Visualisation des données de votre télémétrie dans Application Insights
Application Insights surveille la disponibilité, les performances et l’utilisation de votre application robot, qu’elle soit hébergée dans le cloud ou localement. Il utilise la puissante plateforme d’analyse des données dans Azure Monitor pour vous fournir des insights approfondis sur les opérations de votre application et diagnostiquer les erreurs sans attendre qu’un utilisateur les signale. Il existe plusieurs façons de consulter les données de télémétrie collectées par Application Insights, deux des principales méthodes s’effectuent via des requêtes et le tableau de bord.
Interrogation des données de votre télémétrie dans Application Insights à l’aide des requêtes Kusto
Utilisez cette section comme point de départ pour apprendre à utiliser des requêtes de journal dans Application Insights. Elle illustre deux requêtes utiles et fournit des liens vers d’autres documents contenant des informations supplémentaires.
Pour interroger vos données
Accédez au Portail Azure.
Pour accéder à votre page Application Insights, sélectionnez Surveiller, puis Applications, puis recherchez-le.
Une fois dans votre Application Insights, sélectionnez Journaux (Analytics).
Cela fera apparaître la fenêtre Requête. Entrez la requête suivante et sélectionnez Exécuter :
customEvents | where name=="WaterfallStart" | extend DialogId = customDimensions['DialogId'] | extend InstanceId = tostring(customDimensions['InstanceId']) | join kind=leftouter (customEvents | where name=="WaterfallComplete" | extend InstanceId = tostring(customDimensions['InstanceId'])) on InstanceId | summarize starts=countif(name=='WaterfallStart'), completes=countif(name1=='WaterfallComplete') by bin(timestamp, 1d), tostring(DialogId) | project Percentage=max_of(0.0, completes * 1.0 / starts), timestamp, tostring(DialogId) | render timechart
Cette opération renvoie le pourcentage de boîtes de dialogue en cascade qui s’exécutent jusqu’à leur achèvement.
Conseil
Vous pouvez épingler une requête à votre tableau de bord Application Insights en sélectionnant le bouton en haut à droite du panneau Journaux (Analytics). Il vous suffit de sélectionner le tableau de bord auquel vous voulez épingler la requête pour qu’elle soit disponible lors de votre prochaine visite de ce tableau de bord.
Le tableau de bord Application Insights
Chaque fois que vous créez une ressource Application Insights dans Azure, un nouveau tableau de bord est automatiquement créé et associé. Vous pouvez consulter ce tableau de bord en sélectionnant le bouton en haut du panneau Application Insights, intitulé Tableau de bord de l’application.
Sinon, pour afficher les données, accédez au Portail Azure. Sélectionnez Tableau de bord à gauche, puis sélectionnez le tableau de bord souhaité dans la liste déroulante.
Vous y trouverez des informations par défaut sur les performances de votre robot et des requêtes supplémentaires que vous avez épinglées à votre tableau de bord.