Aggiungere dati di telemetria al bot

SI APPLICA A: SDK v4

La registrazione dei dati di telemetria consente alle applicazioni bot di inviare i dati degli eventi ai servizi di telemetria, ad esempio Application Insights. La telemetria offre informazioni dettagliate sul bot mostrando quali funzionalità vengono usate di più, rileva il comportamento indesiderato e offre visibilità su disponibilità, prestazioni e utilizzo.

Questo articolo descrive come implementare i dati di telemetria nel bot usando Application Insights. Questo articolo riguarda:

  • Codice necessario per collegare i dati di telemetria nel bot e connettersi ad Application Insights.
  • Come abilitare i dati di telemetria nei dialoghi del bot.
  • Come abilitare la telemetria per acquisire i dati di utilizzo da altri servizi, ad esempio i servizi di intelligenza artificiale di Azure.
  • Come visualizzare i dati di telemetria in Application Insights.

Importante

Per un bot a livello di area che potrebbe raccogliere informazioni personali (PII) nei dati di telemetria, la risorsa di Application Insights e la risorsa di Azure Bot devono trovarsi nella stessa area con il bot. Se le risorse si trovano in aree diverse, le informazioni personali potrebbero lasciare l'area geografica del bot.

Prerequisiti

Nota

Il codice di esempio di Application Insights è stato compilato in base al codice di esempio CoreBot. Questo articolo illustra come modificare il codice di esempio CoreBot per incorporare i dati di telemetria. Se si segue in Visual Studio, il codice di esempio di Application Insights sarà disponibile al termine dell'operazione.

Abilitare i dati di telemetria nel bot

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.

Importante

Se non è stato configurato l'account di Application Insights e la chiave di Application Insights è stata creata, eseguire questa operazione prima di procedere.

  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 seguendo la procedura aggiornando il 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 seguendo la procedura aggiornando il 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. Sarà 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 il telemetryClient da esso, quindi non è necessario impostare 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;
        ...
    }
    

Suggerimento

Se si segue e si aggiorna il codice di esempio CoreBot, è possibile fare riferimento al codice di esempio di Application Insights in caso di problemi.

I dati di telemetria vengono ora aggiunti ai dialoghi del bot. Se si esegue ora il bot, si noterà che gli elementi sono stati 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.

Abilitare o disabilitare l'evento di attività e la registrazione delle informazioni personali

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 si desidera, è possibile disabilitare la registrazione eventi attività impostando logActivityTelemetry su false TelemetryInitializerMiddleware nella 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 attività è abilitata, alcune proprietà nelle attività in ingresso/in uscita vengono escluse dalla registrazione perché potrebbero contenere 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);
            });
    ...
}

Verrà quindi illustrato cosa deve essere incluso 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.

Abilitazione della telemetria per acquisire i dati di utilizzo da altri servizi come LUIS e QnA Maker

Nota

Azure AI QnA Maker verrà ritirato il 31 marzo 2025. A partire dal 1 ottobre 2022, non sarà possibile creare nuove risorse QnA Maker o knowledge base. Una versione più recente della domanda e della funzionalità di risposta è ora disponibile come parte del linguaggio di intelligenza artificiale di Azure.

La risposta alle domande personalizzate, una funzionalità di Azure AI Language, è la versione aggiornata del servizio QnA Maker. Per altre informazioni sul supporto di domande e risposte in Bot Framework SDK, vedere Informazioni sul linguaggio naturale.

Nota

Language Understanding (LUIS) verrà ritirato il 1° ottobre 2025. A partire dal 1° aprile 2023, non sarà possibile creare nuove risorse LUIS. Una versione più recente di Language Understanding è ora disponibile come parte del linguaggio di intelligenza artificiale di Azure.

La comprensione del linguaggio di conversazione (CLU), una funzionalità del linguaggio di intelligenza artificiale di Azure, è la versione aggiornata di LUIS. Per altre informazioni sul supporto della comprensione del linguaggio in Bot Framework SDK, vedere Informazioni sul linguaggio naturale.

Verranno ora implementate le funzionalità di telemetria nel servizio LUIS. Il servizio LUIS include la registrazione dei dati di telemetria predefinita, quindi è necessario 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 QnA Maker

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

    public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
    
  2. Abilitare quindi l'oggetto telemetryClient quando si crea LuisRecognizer nel FlightBookingRecognizer costruttore. A tale scopo, aggiungere l'oggetto telemetryClient come 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 dei dati di telemetria in Application Insights.

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

Visualizzazione dei dati di telemetria in Application Insights

Application Insights monitora disponibilità, prestazioni e utilizzo dell'applicazione bot indipendentemente dal fatto che sia ospitata nel cloud o in locale. Usa la potente piattaforma di analisi dei dati in Monitoraggio di Azure per fornire informazioni dettagliate sulle operazioni dell'applicazione e diagnosticare gli errori senza attendere che un utente li segnala. Esistono diversi metodi per visualizzare i dati di telemetria raccolti da Application Insights. Due dei metodi principali usano le query e il dashboard.

Esecuzione di query Kusto nei dati di telemetria in Application Insights

Questa sezione descrive come usare le query di log in Application Insights. Vengono illustrate due query utili e vengono offerti collegamenti ad altra documentazione con ulteriori informazioni.

Per eseguire query sui dati

  1. Accedere al portale di Azure

  2. Per passare alla pagina di Application Insights, selezionare Monitoraggio, quindi Applicazioni e trovarlo.

  3. Una volta in Application Insights, selezionare Log (Analisi).

    Screenshot con il pulsante Log (Analytics) nella pagina Application Insights di un bot.

  4. Viene visualizzata la finestra Query. Immettere la query seguente e selezionare Esegui:

    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
    
  5. Viene restituita la percentuale di finestre di dialogo a cascata eseguite fino al completamento.

    Output di esempio della query di App Insights.

Suggerimento

È possibile aggiungere qualsiasi query al dashboard di Application Insights selezionando il pulsante in alto a destra del pannello Log (Analytics). È sufficiente selezionare il dashboard a cui si vuole aggiungere la query. La query sarà disponibile alla successiva apertura del dashboard.

Dashboard di Application Insights

Ogni volta che si crea una risorsa di Application Insights in Azure, un nuovo dashboard viene automaticamente creato e associato alla risorsa. È possibile visualizzare il dashboard selezionando il pulsante nella parte superiore del pannello di Application Insights denominato dashboard dell'applicazione.

Screenshot con il pulsante Dashboard dell'applicazione nella pagina Application Insights di un bot.

In alternativa, per visualizzare i dati, passare al portale di Azure. Selezionare Dashboard a sinistra, quindi selezionare il dashboard desiderato dall'elenco a discesa.

Verranno visualizzate alcune informazioni predefinite sulle prestazioni del bot ed eventuali query aggiuntive aggiunte al dashboard.

Informazioni aggiuntive