Aggiungere dati di telemetria al bot

• Codice di esempio di CoreBot
• Codice di esempio di Application Insights
• Sottoscrizione a Microsoft Azure
• Chiave di Application Insights
• Conoscenza di Application Insights
• git

• Codice di esempio di CoreBot
• Codice di esempio di Application Insights
• Sottoscrizione a Microsoft Azure
• Chiave di Application Insights
• Conoscenza di Application Insights
• Visual Studio Code
• Node.js versione 10.14 o successiva. Usare il comando node --version per determinare la versione del nodo in uso.
• Bot Framework Emulator

Questo articolo inizia dall'app di esempio CoreBot e aggiunge il codice necessario per integrare i dati di telemetria in qualsiasi bot. Questa operazione consentirà ad Application Insights di iniziare a tenere traccia delle richieste.

1. Aprire l'app di esempio CoreBot in Visual Studio.

2. Aggiungere il pacchetto NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Per altre informazioni sull'uso di NuGet, vedere Installare e gestire i pacchetti in Visual Studio:

3. Inserire le istruzioni seguenti in 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;
   

   Suggerimento

   Se si sta eseguendo l'aggiornamento del codice di esempio CoreBot, si noterà che l'istruzione using per Microsoft.Bot.Builder.Integration.AspNet.Core esiste già nell'esempio CoreBot.

4. Inserire il codice seguente nel metodo ConfigureServices() in Startup.cs. Ciò consentirà di rendere disponibili i servizi di telemetria nel bot tramite l'inserimento di dipendenze:

   // 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>();
       ...
   }
   

   Suggerimento

   Se si sta eseguendo l'aggiornamento del codice di esempio CoreBot, si noterà che services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); esiste già.

5. Indicare all'adapter di usare il codice middleware aggiunto al metodo ConfigureServices(). A tale scopo AdapterWithErrorHandler.cs , usare il parametro TelemetryInitializerMiddleware telemetryInitializerMiddleware nell'elenco dei parametri del costruttore e l'istruzione Use(telemetryInitializerMiddleware); nel costruttore, come illustrato di seguito:

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

6. È anche necessario aggiungere Microsoft.Bot.Builder.Integration.ApplicationInsights.Core all'elenco di istruzioni using in AdapterWithErrorHandler.cs.

7. Aggiungere la chiave di strumentazione di Application Insights nel file appsettings.json. Il appsettings.json file contiene i metadati relativi ai servizi esterni usati dal bot durante l'esecuzione. Ad esempio, cosmos DB, Application Insights e la connessione ai servizi di intelligenza artificiale di Azure e i metadati vengono archiviati in questa posizione. L'aggiunta al file appsettings.json deve avere il formato seguente:

   {
       "MicrosoftAppId": "",
       "MicrosoftAppPassword": "",
       "ApplicationInsights": {
           "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
       }
   }
   

   Nota

   informazioni dettagliate su come ottenere la chiave di strumentazione di Application Insights sono disponibili nell'articolo Chiavi di Application Insights.

A questo punto, viene eseguito il lavoro preliminare per abilitare la telemetria con Application Insights. È possibile eseguire il bot in locale usando l'emulatore e quindi passare ad Application Insights per vedere cosa viene registrato, ad esempio il tempo di risposta, l'integrità complessiva delle app e le informazioni generali sull'esecuzione.

Abilitare i dati di telemetria nelle finestre di dialogo del bot

Quando si aggiunge un nuovo dialogo a qualsiasi elemento ComponentDialog, questo erediterà la classe Microsoft.Bot.Builder.IBotTelemetryClient del relativo dialogo padre. Nell'applicazione di esempio CoreBot, ad esempio, tutte le finestre di dialogo vengono aggiunte a MainDialog, ovvero componentDialog. Dopo aver impostato la proprietà TelemetryClient su MainDialog, tutte le finestre di dialogo aggiunte erediteranno automaticamente la proprietà telemetryClient da essa, quindi non è necessario impostarla in modo esplicito quando si aggiungono finestre di dialogo.

Per aggiornare l'esempio di CoreBot, seguire questa procedura:

1. In MainDialog.cs aggiornare l'elenco di parametri del costruttore in modo da includere il parametro IBotTelemetryClient e quindi impostare la proprietà TelemetryClient di MainDialog su tale valore, come illustrato nel frammento di codice seguente:

   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;
       ...
   }
   

I dati di telemetria vengono ora aggiunti alle finestre di dialogo del bot. Se si esegue ora il bot, si noterà che gli elementi vengono registrati in Application Insights; Tuttavia, se si dispone di una tecnologia integrata, ad esempio un servizio di intelligenza artificiale di Azure, sarà necessario aggiungere anche a TelemetryClient tale codice.

Questo articolo inizia con l'app di esempio CoreBot e aggiunge il codice necessario per integrare i dati di telemetria in qualsiasi bot. Questa operazione consentirà ad Application Insights di iniziare a tenere traccia delle richieste.

1. Aprire l'app di esempio CoreBot in Visual Studio Code.

2. Aggiungere la chiave di Application Insights al .env file: InstrumentationKey=<EnterInstrumentationKeyHere>. Il .env file contiene i metadati relativi ai servizi esterni usati dal bot durante l'esecuzione. Ad esempio, application insights e la connessione ai servizi di intelligenza artificiale di Azure e i metadati vengono archiviati in questa posizione. L'aggiunta al file .env deve avere il formato seguente:

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

   Nota

   informazioni dettagliate su come ottenere la chiave di strumentazione di Application Insights sono disponibili nell'articolo Chiavi di Application Insights.

3. Aggiungere un riferimento ai moduli ApplicationInsightsTelemetryClient e TelemetryInitializerMiddleware che si trovano in botbuilder-applicationinsights in Bot Framework SDK. A tale scopo, aggiungere il codice seguente a partire dalla parte superiore di index.js, subito dopo il codice per importare i pacchetti necessari:

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

   Suggerimento

   Gli esempi di bot JavaScript usano Node.js, che segue il sistema di moduli CommonJS e la funzione predefinita require per includere moduli presenti in file separati.

4. Creare una nuova funzione alla fine di denominata getTelemetryClient che accetta la chiave di strumentazione come parametro e restituisce un client di index.js telemetria usando il ApplicationInsightsTelemetryClient modulo a cui si è fatto riferimento in precedenza. Questo client di telemetria è la posizione in cui verranno inviati i dati di telemetria, in questo caso 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. Successivamente, è necessario aggiungere il middleware di telemetria alla pipeline middleware dell'adapter. A tale scopo, aggiungere il codice seguente, iniziando subito dopo il codice di gestione degli errori:

   
   // 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. Per consentire alla finestra di dialogo di segnalare i dati di telemetria, è telemetryClient necessario che corrisponda a quello usato per il middleware di telemetria, ovvero 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. Dopo aver creato l'oggetto server Web HTTP restify, indicare all'oggetto di usare il bodyParser gestore.

       }
       return new NullTelemetryClient();
   }
   

   Suggerimento

   In questo modo viene usata la funzione restifybodyParser. restify è un "framework di servizi Web Node.js ottimizzato per la compilazione semanticamente corretta dei servizi Web RESTful pronti per l'uso in produzione su larga scala. restify ottimizza l'introspezione e le prestazioni e viene usato in alcune delle distribuzioni di Node.js più grandi sulla Terra." Per altre informazioni, vedere il sito Web restify .

   Node.js segue il sistema di moduli CommonJS e usa la funzione predefinita require per includere moduli presenti in file separati.

A questo punto, viene eseguito il lavoro preliminare per abilitare la telemetria con Application Insights. È possibile eseguire il bot in locale usando l'emulatore e quindi passare ad Application Insights per vedere cosa viene registrato, ad esempio il tempo di risposta, l'integrità complessiva delle app e le informazioni generali sull'esecuzione.

Abilitare o disabilitare la registrazione attività

Per impostazione predefinita, TelemetryInitializerMiddleware userà TelemetryLoggerMiddleware per registrare i dati di telemetria quando il bot invia/riceve attività. Durante la registrazione delle attività vengono creati log eventi personalizzati nella risorsa di Application Insights. Se lo si desidera, è possibile disabilitare la registrazione degli eventi attività impostando su logActivityTelemetry false in durante la TelemetryInitializerMiddleware registrazione in 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);
            });
    ...
}

Abilitare o disabilitare la registrazione delle informazioni personali

Per impostazione predefinita, se la registrazione delle attività è abilitata, alcune proprietà sulle attività in ingresso/in uscita vengono escluse dalla registrazione perché probabilmente contengono informazioni personali, ad esempio il nome utente e il testo dell'attività. È possibile scegliere di includere queste proprietà nella registrazione apportando la modifica seguente in Startup.cs durante la registrazione di 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);
            });
    ...
}

Verranno ora visualizzati gli elementi da includere per aggiungere funzionalità di telemetria ai dialoghi. In questo modo sarà possibile ottenere informazioni aggiuntive, ad esempio le finestre di dialogo eseguite e le statistiche su ogni finestra.

Abilitare o disabilitare la registrazione attività

Per impostazione predefinita, TelemetryInitializerMiddleware userà per TelemetryLoggerMiddleware registrare i dati di telemetria quando il bot invia o riceve attività. Durante la registrazione delle attività vengono creati log eventi personalizzati nella risorsa di Application Insights. Se lo si desidera, è possibile disabilitare la registrazione degli eventi attività impostando su logActivityTelemetry false in durante la TelemetryInitializerMiddleware registrazione in index.js.

Il frammento di codice seguente proviene dall'esempio 21.corebot-app-insightse mostra la chiamata a 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();

Il frammento di codice seguente mostra la modifica necessaria nell'esempio 21.corebot-app-insights, nella chiamata a per TelemetryInitializerMiddleware disabilitare la registrazione attività:

// 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);

Abilitare o disabilitare la registrazione delle informazioni personali

Quando la registrazione delle attività è abilitata, alcune proprietà delle attività in ingresso/in uscita vengono escluse dalla registrazione per impostazione predefinita, perché è probabile che contengano informazioni personali, ad esempio il nome utente e il testo dell'attività. È possibile scegliere di includere queste proprietà nella registrazione modificando il logPersonalInformation parametro da false a true quando si registra TelemetryLoggerMiddleware in index.js.

// 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();

Verranno ora visualizzati gli elementi da includere per aggiungere funzionalità di telemetria ai dialoghi. In questo modo sarà possibile ottenere informazioni aggiuntive, ad esempio le finestre di dialogo eseguite e le statistiche su ogni finestra.

La funzionalità di telemetria verrà implementata successivamente nel servizio LUIS. Il servizio LUIS ha la registrazione dei dati di telemetria predefinita disponibile, quindi è sufficiente iniziare a ottenere i dati di telemetria da LUIS. Se si è interessati ad abilitare i dati di telemetria in un bot abilitato per QnA Maker, vedere Aggiungere dati di telemetria al bot di QnA Maker

1. Il parametro IBotTelemetryClient telemetryClient è obbligatorio nel costruttore FlightBookingRecognizer in FlightBookingRecognizer.cs:

   public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
   

2. Abilitare quindi quando telemetryClient si crea LuisRecognizer nel FlightBookingRecognizer costruttore . A tale scopo, aggiungere come telemetryClient nuovo 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);
   }
   

A questo punto si avrà a disposizione un bot funzionale che registra i dati di telemetria in Application Insights. È possibile usare Bot Framework Emulator per eseguire il bot in locale. Sebbene non vengano rilevati cambiamenti nel comportamento del bot, il bot registrerà le informazioni in Application Insights. Interagire con il bot inviando più messaggi e nella sezione successiva verranno esaminati i risultati della telemetria in Application Insights.

Per informazioni sul test e il debug del bot, è possibile fare riferimento agli articoli seguenti:

• Eseguire il debug di un bot
• Linee guida per test e debug
• Eseguire il debug con l'emulatore

La funzionalità di telemetria verrà implementata successivamente nel servizio LUIS. Il servizio LUIS ha la registrazione dei dati di telemetria predefinita disponibile, quindi è sufficiente iniziare a ottenere i dati di telemetria da LUIS.

Per abilitare il client di telemetria nel sistema di riconoscimento LUIS:

1. Apri FlightBookingRecognizer.js

2. Passare il telemetryClient parametro al FlightBookingRecognizer costruttore:

   constructor(config, telemetryClient) {
   

3. Impostare il telemetryClient campo dell'oggetto recognizerOptions sulla telemetryClient proprietà passata al FlightBookingRecognizer costruttore, una volta completato il costruttore verrà visualizzato come segue:

   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. Infine, è necessario includere quando si crea un'istanza telemetryClient FlightBookingRecognizer di in index.js:

   const memoryStorage = new MemoryStorage();
   

Questo è tutto; è necessario disporre di un bot funzionale che registra i dati di telemetria in Application Insights. È possibile usare Bot Framework Emulator per eseguire il bot in locale. Sebbene non vengano rilevati cambiamenti nel comportamento del bot, il bot registrerà le informazioni in Application Insights. Interagire con il bot inviando più messaggi e la sezione successiva descrive come esaminare i risultati della telemetria in Application Insights.

Per informazioni sul test e il debug del bot, è possibile fare riferimento agli articoli seguenti:

• Eseguire il debug di un bot
• Linee guida per test e debug
• Eseguire il debug con l'emulatore