Ajouter la télémétrie à votre bot

• 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

• 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
• Visual Studio Code
• Node.js version 10.14 ou ultérieure. Utilisez la commande node --version pour déterminer la version du nœud dont vous disposez.
• Bot Framework Emulator

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.

1. Ouvrez l’exemple d’application CoreBot dans Visual Studio.

2. 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 :

3. 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.

4. Ajoutez le code suivant à la méthode ConfigureServices() dans Startup.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à.

5. Demandez à l’adaptateur d’utiliser le code de l’intergiciel qui a été ajouté à la méthode ConfigureServices(). Pour ce AdapterWithErrorHandler.cs faire, utilisez le paramètre TelemetryInitializerMiddleware telemetryInitializerMiddleware dans la liste des paramètres du constructeur et l’instruction Use(telemetryInitializerMiddleware); dans le constructeur, comme illustré ici :

       public AdapterWithErrorHandler(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger, TelemetryInitializerMiddleware telemetryInitializerMiddleware, ConversationState conversationState = null)
           : base(configuration, logger)
   {
       ...
       Use(telemetryInitializerMiddleware);
   }
   

6. Vous devez également ajouter Microsoft.Bot.Builder.Integration.ApplicationInsights.Core à votre liste d’instructions using dans AdapterWithErrorHandler.cs.

7. Ajoutez la clé d’instrumentation Application Insights à votre fichier appsettings.json. Le appsettings.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 fichier appsettings.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 :

1. Dans MainDialog.cs, mettez à jour la liste des paramètres de constructeur afin d'inclure le paramètre IBotTelemetryClient, 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;
       ...
   }
   

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.

Cet article commence par 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.

1. Ouvrez l’exemple d’application CoreBot dans Visual Studio Code.

2. Ajoutez la clé Application Insights à votre .env fichier : InstrumentationKey=<EnterInstrumentationKeyHere>. Le .env fichier contient des métadonnées sur les services externes que le bot utilise lors de l’exécution. Par exemple, Application Insights et la connexion et les métadonnées des services Azure AI sont stockés ici. L’ajout à votre fichier .env doit être au format suivant :

   MicrosoftAppType=
   MicrosoftAppId=
   MicrosoftAppPassword=
   MicrosoftAppTenantId=
   LuisAppId=
   LuisAPIKey=
   LuisAPIHostName=
   InstrumentationKey=
   

   Remarque

   Pour plus d’informations sur l’obtention de la clé d’instrumentation Application Insights, consultez l’article clés Application Insights.

3. Ajoutez une référence aux modules ApplicationInsightsTelemetryClient et TelemetryInitializerMiddleware qui se trouvent dans botbuilder-applicationinsights le Kit de développement logiciel (SDK) Bot Framework. Pour ce faire, ajoutez le code suivant à partir du haut de , juste après l’importation des index.jspackages requis :

   const { ApplicationInsightsTelemetryClient, TelemetryInitializerMiddleware } = require('botbuilder-applicationinsights');
   const { TelemetryLoggerMiddleware } = require('botbuilder-core');
   

   Conseil

   Les exemples de bot JavaScript utilisent Node.js, qui suit le système de module CommonJS et la fonction intégrée require pour inclure des modules qui existent dans des fichiers distincts.

4. Créez une fonction à la fin du nom getTelemetryClient qui prend votre clé d’instrumentation en tant que paramètre et retourne un client de index.js télémétrie à l’aide du ApplicationInsightsTelemetryClient module que vous avez précédemment référencé. Ce client de télémétrie est l’emplacement auquel vos données de télémétrie seront envoyées, dans ce cas Application Insights.

   // Listen for Upgrade requests for Streaming.
   server.on('upgrade', async (req, socket, head) => {
       // Create an adapter scoped to this WebSocket connection to allow storing session data.
       const streamingAdapter = new CloudAdapter(botFrameworkAuthentication);
   
       // Set onTurnError for the CloudAdapter created for each connection.
       streamingAdapter.onTurnError = onTurnErrorHandler;
   

5. Ensuite, vous devez ajouter le middleware de télémétrie au pipeline d’intergiciels d’adaptateur. Pour ce faire, ajoutez le code suivant, en commençant juste après le code de gestion des erreurs :

   
   // For local development, in-memory storage is used.
   // CAUTION: The Memory Storage used here is for local bot debugging only. When the bot
   // is restarted, anything stored in memory will be gone.
   const memoryStorage = new MemoryStorage();
   

6. Pour que votre boîte de dialogue signale les données de télémétrie, elle telemetryClient doit correspondre à celle utilisée pour l’intergiciel de télémétrie, autrement dit, dialog.telemetryClient = telemetryClient;

   const server = restify.createServer();
   server.listen(process.env.port || process.env.PORT || 3978, function() {
       console.log(`\n${ server.name } listening to ${ server.url }`);
       console.log('\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator');
       console.log('\nTo talk to your bot, open the emulator select "Open Bot"');
   });
   

7. Après avoir créé l’objet serveur web HTTP restify, demandez-lui d’utiliser le bodyParser gestionnaire.

       }
       return new NullTelemetryClient();
   }
   

   Conseil

   Cela utilise la fonction restifybodyParser. restify est un « infrastructure de service web Node.js optimisée pour générer des services web RESTful corrects sémantiquement prêts pour une utilisation en production à grande échelle. restify optimise l’introspection et les performances, et est utilisé dans certains des plus grands déploiements Node.js sur Terre. Pour plus d’informations, consultez le site web restify .

   Node.js suit le système de module CommonJS et utilise la fonction intégrée require pour inclure des modules qui existent dans des fichiers distincts.

À 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 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.

Activer ou désactiver la journalisation des activités

Par défaut, le TelemetryInitializerMiddleware fichier utilise la TelemetryLoggerMiddleware fonction de journalisation des données de télémétrie lorsque votre bot envoie ou 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 lors de l’inscription TelemetryInitializerMiddleware dans index.js.

L’extrait de code suivant provient de l’exemple 21.corebot-app-insightset affiche l’appel à TelemetryInitializerMiddleware:

// For local development, in-memory storage is used.
// CAUTION: The Memory Storage used here is for local bot debugging only. When the bot
// is restarted, anything stored in memory will be gone.
const memoryStorage = new MemoryStorage();

L’extrait de code ci-dessous montre la modification nécessaire dans l’exemple 21.corebot-app-insights, dans l’appel pour TelemetryInitializerMiddleware désactiver la journalisation des activités :

// Add telemetry middleware to the adapter middleware pipeline
var telemetryClient = getTelemetryClient(process.env.InstrumentationKey);
var telemetryLoggerMiddleware = new TelemetryLoggerMiddleware(telemetryClient);
var initializerMiddleware = new TelemetryInitializerMiddleware(telemetryLoggerMiddleware, false);
adapter.use(initializerMiddleware);

Activer ou désactiver la journalisation des informations personnelles

Lorsque la journalisation des activités est activée, certaines propriétés sur les activités entrantes/sortantes sont exclues de la journalisation par défaut, 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 modifiant le logPersonalInformation paramètre de celui-ci true lors de false l’inscription de l’index.jsTelemetryLoggerMiddleware.

// For local development, in-memory storage is used.
// CAUTION: The Memory Storage used here is for local bot debugging only. When the bot
// is restarted, anything stored in memory will be gone.
const memoryStorage = new MemoryStorage();

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.

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

1. Le paramètre IBotTelemetryClient telemetryClient est obligatoire dans le constructeur FlightBookingRecognizer de FlightBookingRecognizer.cs :

   public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
   

2. Ensuite, activez le telemetryClient moment où vous créez votre FlightBookingRecognizer LuisRecognizer constructeur. Pour ce faire, ajoutez-le telemetryClient 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 :

• Déboguer un bot
• Recommandations en matière de test et de débogage
• Déboguer avec l’émulateur

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.

Pour activer le client de télémétrie dans votre module de reconnaissance LUIS :

1. Ouvrir FlightBookingRecognizer.js

2. Passez le telemetryClient paramètre au FlightBookingRecognizer constructeur :

   constructor(config, telemetryClient) {
   

3. Définissez le telemetryClient champ de l’objet recognizerOptions sur la telemetryClient propriété passée dans le FlightBookingRecognizer constructeur, une fois que votre constructeur a terminé, il apparaît comme suit :

   if (luisIsConfigured) {
       // Set the recognizer options depending on which endpoint version you want to use e.g v2 or v3.
       // More details can be found in https://docs.microsoft.com/azure/cognitive-services/luis/luis-migration-api-v3
       const recognizerOptions = {
           apiVersion: 'v3',
           telemetryClient: telemetryClient
       };
   
       this.recognizer = new LuisRecognizer(config, recognizerOptions);
   }
   

4. Enfin, vous devez inclure l’instance telemetryClient lors de la création d’une instance dans FlightBookingRecognizer index.js:

   const memoryStorage = new MemoryStorage();
   

Voilà; vous devez disposer d’un bot fonctionnel qui journalise 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 la section suivante explique comment passer en revue 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 :

• Déboguer un bot
• Recommandations en matière de test et de débogage
• Déboguer avec l’émulateur