Adición de telemetría a un bot de QnAAdd telemetry to your QnAMaker bot

se aplica a: SDK V4APPLIES TO: SDK v4

En la versión 4.2 de SDK Bot Framework, se agregó el registro de datos de telemetría.Telemetry logging was added to version 4.2 of the Bot Framework SDK. Esto permite que las aplicaciones de bot envíen datos de eventos a servicios de telemetría como Application Insights.This enables bot applications to send event data to telemetry services such as Application Insights. La telemetría ofrece información al bot mostrando las características que se usan con mayor frecuencia, permite detectar comportamientos no deseados y ofrece visibilidad sobre la disponibilidad, el rendimiento y el uso.Telemetry offers insights into your bot by showing which features are used the most, detects unwanted behavior and offers visibility into availability, performance, and usage.

Se han agregado dos nuevos componentes al SDK Bot Framework que habilitan el registro de telemetría en los bots habilitados para QnA Maker: TelemetryLoggerMiddleware y la clase QnAMaker.Two new components were added to the Bot Framework SDK that enable telemetry logging in QnA Maker enabled bots: TelemetryLoggerMiddleware and the QnAMaker class. TelemetryLoggerMiddleware es un componente de middleware que registra cada vez que se reciben, envían, actualizan o eliminan mensajes, y la clase "QnAMaker" proporciona un registro personalizado que amplía las funcionalidades de telemetría.TelemetryLoggerMiddleware is a middleware component that logs every time messages are received, sent, updated, or deleted, and the 'QnAMaker' class provides custom logging that extends telemetry capabilities.

En este artículo, aprenderá lo siguiente:In this article you will learn about:

  • El código necesario para integrar la telemetría en el bot.The code required to wire up telemetry in your bot

  • El código necesario para habilitar el registro y los informes predefinidos de QnA que usan las propiedades de evento estándar.The code required to enable the out-of-the-box QnA logging and reports that use the standard event properties.

  • Cómo modificar o extender las propiedades de evento predeterminadas del SDK para atender a una amplia variedad de necesidades de informes.Modifying or extending the SDK's default event properties to enable a wide range of reporting needs.

PrerrequisitosPrerequisites

Nota

Este artículo se basará en el código de ejemplo de QnA Maker y le guiará por los pasos necesarios para incorporar la telemetría.This article will build on the QnA Maker sample code by stepping you through the steps required to incorporate telemetry.

Integración de la telemetría en un bot de QnA MakerWiring up telemetry in your QnA Maker bot

Vamos a empezar con la aplicación de ejemplo de QnA Maker y agregaremos el código necesario para integrar la telemetría en cualquier bot.We will start with the QnA Maker sample app and add the code required to integrate telemetry into a bot using the QnA service. Esto permitirá a Application Insights empezar a realizar el seguimiento de solicitudes.This will enable Application Insights to begin tracking requests.

  1. Abra la aplicación de ejemplo de QnA Maker en Visual Studio.Open the QnA Maker sample app in Visual Studio

  2. Agregue el paquete NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core .Add the Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet package. Para más información sobre el uso de NuGet, consulte Instalación y administración de paquetes en Visual Studio:For more information on using NuGet, see Install and manage packages in Visual Studio:

  3. Incluya las siguientes instrucciones en Startup.cs:Include the following statements in Startup.cs:

    using Microsoft.ApplicationInsights.Extensibility;
    using Microsoft.Bot.Builder.ApplicationInsights;
    using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
    

    Nota

    Si continúa con la actualización del código de ejemplo de QnA Maker, observará que la instrucción using de Microsoft.Bot.Builder.Integration.AspNet.Core ya existe en el ejemplo.If you're following along by updating the QnA Maker sample code you will notice that the using statement for Microsoft.Bot.Builder.Integration.AspNet.Core already exists in the QnA Maker sample.

  4. Agregue el siguiente código al método ConfigureServices() en Startup.cs.Add the following code to the ConfigureServices() method in Startup.cs. Esto hará que los servicios de telemetría estén disponibles para el bot mediante la inserción de dependencias:This makes telemetry services available to your bot via dependency injection (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();
    
        // Add the standard telemetry client
        services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>();
    
        // Create the telemetry middleware to track conversation events
        services.AddSingleton<TelemetryLoggerMiddleware>();
    
        // Add the telemetry initializer middleware
        services.AddSingleton<IMiddleware, TelemetryInitializerMiddleware>();
    
        // 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>();
        ...
    }
    

    Nota

    Si continúa con la actualización del código de ejemplo de QnA Maker, observará que services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); ya existe.If you are following along by updating the QnA Maker sample code you will notice that services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); already exists.

  5. Indique al adaptador que use el código de middleware que se agregó al método ConfigureServices().Instruct the adapter to use the middleware code that was added to the ConfigureServices() method. Abra AdapterWithErrorHandler.cs y agregue IMiddleware middleware a la lista de parámetros de constructores.Open AdapterWithErrorHandler.cs and add IMiddleware middleware to the constructors parameter list. Agregue la instrucción Use(middleware); como la última línea del constructor:Add the Use(middleware); statement as the last line in the contructor:

    public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
            : base(credentialProvider)
    {
        ...
    
        Use(middleware);
    }
    
  6. Agregue la clave de instrumentación de Application Insights a su archivo appsettings.json.Add the Application Insights instrumentation key in your appsettings.json file. El archivo appsettings.json contiene metadatos sobre los servicios externos que el bot usa mientras se ejecuta.The appsettings.json file contains metadata about external services the Bot uses while running. Por ejemplo, aquí se almacenan los metadatos y la conexión de servicio de CosmosDB, Application Insights y QnA Maker.For example, CosmosDB, Application Insights and the QnA Maker service connection and metadata is stored there. La adición al archivo appsettings.json debe estar en este formato:The addition to your appsettings.json file must be in this format:

    {
        "MicrosoftAppId": "",
        "MicrosoftAppPassword": "",
        "QnAKnowledgebaseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "QnAEndpointKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "QnAEndpointHostName": "https://xxxxxxxx.azurewebsites.net/qnamaker",
        "ApplicationInsights": {
            "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }
    }
    

    Nota

    • Puede encontrar información detallada sobre cómo obtener la clave de instrumentación de Application Insights en el artículo Claves de Application Insights.Details on getting the Application Insights instrumentation key can be found in the article Application Insights keys.
    • Ya debe tener una cuenta de QnA Maker,si es necesario, puede encontrar información sobre cómo obtener los valores de Id. de la base de conocimiento de QnA, Clave de punto de conexión y Nombre De Host en el artículo administración de claves.You should already have a QnA maker account, if needed you can find information on getting the QnA Knowledgebase Id, Endpoint Key and HostName values in the key management article.

En este punto, ya se ha realizado el trabajo preliminar para habilitar la telemetría mediante Application Insights.At this point the preliminary work to enable telemetry using Application Insights is done. Puede ejecutar el bot localmente mediante el emulador del bot y, a continuación, ir a Application Insights para ver lo que se registra, como el tiempo de respuesta, el estado general de la aplicación y la información general de ejecución.You can run your bot locally using the bot Emulator and then go into Application Insights to see what is being logged such as response time, overall app health, and general running information.

Sugerencia

Para más información sobre cómo habilitar o deshabilitar el registro de información personal y de eventos de actividad, consulte Adición de telemetría al bot.For information on Enabling / disabling activity event and personal information logging see Add telemetry to your bot

A continuación, vamos a ver qué hay que incluir para agregar la funcionalidad de telemetría al servicio de QnA Maker.Next we will see what needs to be included to add telemetry functionality to the QnA Maker service.

Habilitación de la telemetría para capturar datos de uso del servicio QnA MakerEnabling telemetry to capture usage data from the QnA Maker service

El servicio QnA Maker incluye un registro de telemetría integrado disponible, por lo que hay muy poco que deba hacer para empezar a obtener datos de telemetría de QnA Maker.The QnA Maker service has built-in telemetry logging available so there is very little you need to do to start getting telemetry data from QnA Maker. En primer lugar, veremos cómo incorporar la telemetría en el código de QnA Maker para habilitar el registro de telemetría integrado. A continuación, veremos cómo reemplazar o agregar propiedades adicionales a los datos de evento existentes para satisfacer una amplia gama de necesidades de informes.First we will see how to incorporate telemetry into the QnA Maker code to enable the built-in telemetry logging, then we will learn how to replace or add additional properties to the existing event data to satisfy a wide range of reporting needs.

Habilitación del registro predeterminado de QnAEnabling default QnA logging

  1. Cree un campo de solo lectura privado de tipo IBotTelemetryClient en la clase QnABot en QnABot.cs:Create a private readonly field of type IBotTelemetryClient in your QnABot class in QnABot.cs:

    public class QnABot : ActivityHandler
        {
            private readonly IBotTelemetryClient _telemetryClient;
            ...
    }
    
  2. Agregue un parámetro IBotTelemetryClient al constructor de la clase QnABot en QnABot.cs y asigne su valor al campo privado creado en el paso anterior:Add an IBotTelemetryClient parameter to your QnABot class constructor in QnABot.cs and assign its value to the private field created in the previous step:

    public QnABot(IConfiguration configuration, ILogger<QnABot> logger, IHttpClientFactory httpClientFactory, IBotTelemetryClient telemetryClient)
    {
        ...
        _telemetryClient = telemetryClient;
    }
    
  3. Se requiere el parámetro telemetryClient al crear una instancia del nuevo objeto QnAMaker en QnABot.cs:The telemetryClient parameter is required when instantiating the new QnAMaker object in QnABot.cs:

    var qnaMaker = new QnAMaker(new QnAMakerEndpoint
                {
                    KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                    EndpointKey = _configuration["QnAEndpointKey"],
                    Host = _configuration["QnAEndpointHostName"]
                },
                null,
                httpClient,
                _telemetryClient);
    

    Sugerencia

    Asegúrese de que los nombres de propiedad que usa en las entradas coinciden con los nombres de propiedad que usó en el archivo AppSettings.jsy que los valores de esas propiedades se obtienen seleccionando el botón Ver código en la página Mis bases de conocimiento del _configuration portal de QnA Maker: Make sure that the property names that you use in the _configuration entries match the property names you used in the AppSettings.json file and the values for those properties are obtained by selecting the View Code button on the My knowledge bases page in the QnA Maker portal:

    AppSettings

Visualización de los datos de telemetría registrados desde las entradas predeterminadas de QnA MakerViewing Telemetry data logged from the QnA Maker default entries

Puede ver los resultados del uso del bot QnA Maker en Application Insights después de ejecutar el bot en el emulador del bot siguiendo estos pasos:You can view the results of your QnA Maker bot usage in Application Insights after running your bot in the bot Emulator by taking the following steps :

  1. Vaya a Azure Portal.Go to the Azure portal

  2. Haga clic en Monitor > Aplicaciones para ir a Application Insights.Navigate to your Application Insights by clicking on Monitor > Applications.

  3. Cuando esté en su aplicación de Application Insights, haga clic en Registros (Analytics) en la barra de navegación, como se muestra a continuación:Once in your Application Insights, click on Logs (Analytics) on the navigation bar as shown below:

    Log Analytics

  4. Escriba la siguiente consulta de Kusto y seleccione Ejecutar.Enter the following Kusto query and then select Run

    customEvents
    | where name == 'QnaMessage'
    | extend answer = tostring(customDimensions.answer)
    | summarize count() by answer
    
  5. Deje esta página abierta en el explorador; volveremos a ella después de agregar una nueva propiedad personalizada.Leave this page open in your browser, we will come back to it after adding a new custom property.

Sugerencia

Si no está familiarizado con el lenguaje de consulta de Kusto que se usa para escribir consultas de registros en Azure Monitor, pero está familiarizado con el lenguaje de consulta SQL, es posible que la hoja de referencia de consultas de SQL a registros de Azure Monitor le resulte útil.If you are new to the Kusto query language that is used to write log queries in Azure Monitor, but are familiar with SQL query language, you may find the SQL to Azure Monitor log query cheat sheet useful.

Modificación o extensión de las propiedades de evento predeterminadasModifying or extending the default event properties

Si necesita propiedades que no están definidas en la clase QnAMaker, hay dos maneras de abordarlo y ambas requieren que cree su propia clase derivada de la clase QnAMaker.If you need properties that are not defined in the QnAMaker class there are two ways of handling this, both require creating your own class derived from the QnAMaker class. La primera se explica en la sección siguiente titulada Adición de propiedades, en la que se agregan propiedades al evento QnAMessage existente.The first is explained in the section below titled Adding properties in which you add properties to the existing QnAMessage event. El segundo método le permite crear nuevos eventos a los que puede agregar propiedades, tal y como se describe en Adición de nuevos eventos con propiedades personalizadas.The second method allows you to create new events to which you can add properties as described in Adding new events with custom properties.

Nota

El evento QnAMessage forma parte del SDK Bot Framework y proporciona todas las propiedades de evento predefinidas que se registran en Application Insights.The QnAMessage event is part of the Bot Framework SDK and provides all of the out-of-the-box event properties that are logged to Application Insights.

Adición de propiedadesAdding properties

En el siguiente ejemplo se muestra la derivación desde la clase QnAMaker.The following demonstrates how you can derive from the QnAMaker class. En el ejemplo se muestra cómo agregar la propiedad "MyImportantProperty" al evento QnAMessage.The example shows adding the property "MyImportantProperty" to the QnAMessage event. El evento QnAMessage se registra cada vez que se realiza una llamada a GetAnswers de QnA.The QnAMessage event is logged every time a QnA GetAnswers call is performed.

Después de aprender a agregar propiedades personalizadas, aprenderá a crear un nuevo evento personalizado y asociarle propiedades. Después, ejecutaremos el bot localmente mediante el emulador de Bot Framework y verá lo que se registra en Application Insights mediante el lenguaje de consulta Kusto.After learning how to add custom properties we will learn how to create a new custom event and associate properties with it, then we will run the bot locally using the Bot Framework Emulator and see what is being logged in Application Insights using the Kusto query language.

  1. Cree una nueva clase llamada MyQnAMaker en el espacio de nombres Microsoft.BotBuilderSamples que herede de la clase QnAMaker, y guárdela como MyQnAMaker.cs.Create a new class named MyQnAMaker in the Microsoft.BotBuilderSamples namespace that inherits from the QnAMaker class and save it as MyQnAMaker.cs. Para heredar de la clase QnAMaker, deberá agregar la instrucción using Microsoft.Bot.Builder.AI.QnA.In order to inherit from the QnAMaker class you will need to add the Microsoft.Bot.Builder.AI.QnA using statement. El código tendrá el siguiente aspecto:Your code should appear as follows:

    using Microsoft.Bot.Builder.AI.QnA;
    
    namespace Microsoft.BotBuilderSamples
    {
        public class MyQnAMaker : QnAMaker
        {
    
        }
    }
    
  2. Agregue un constructor de clase a MyQnAMaker.Add a class constructor to MyQnAMaker. Tenga en cuenta que necesitará dos instrucciones using adicionales para los parámetros de constructor System.Net.Http y Microsoft.Bot.Builder:Note that you will need two additional using statements for the constructors parameters System.Net.Http and Microsoft.Bot.Builder:

    ...
    using Microsoft.Bot.Builder.AI.QnA;
    using System.Net.Http;
    using Microsoft.Bot.Builder;
    
    namespace Microsoft.BotBuilderSamples
    {
        public class MyQnAMaker : QnAMaker
        {
            public MyQnAMaker(
                QnAMakerEndpoint endpoint,
                QnAMakerOptions options = null,
                HttpClient httpClient = null,
                IBotTelemetryClient telemetryClient = null,
                bool logPersonalInformation = false)
                : base(endpoint, options, httpClient, telemetryClient, logPersonalInformation)
            {
    
            }
        }
    }
    
  3. Agregue la nueva propiedad al evento QnAMessage después del constructor e incluya las instrucciones System.Collections.Generic, System.Threading y System.Threading.Tasks:Add the new property to the QnAMessage event after the constructor and include the statements System.Collections.Generic, System.Threading, and System.Threading.Tasks:

    using Microsoft.Bot.Builder.AI.QnA;
    using System.Net.Http;
    using Microsoft.Bot.Builder;
    using System.Collections.Generic;
    using System.Threading;
    using System.Threading.Tasks;
    
    namespace Microsoft.BotBuilderSamples
    {
            public class MyQnAMaker : QnAMaker
            {
            ...
    
            protected override async Task OnQnaResultsAsync(
                                QueryResult[] queryResults,
                                Microsoft.Bot.Builder.ITurnContext turnContext,
                                Dictionary<string, string> telemetryProperties = null,
                                Dictionary<string, double> telemetryMetrics = null,
                                CancellationToken cancellationToken = default(CancellationToken))
            {
                var eventData = await FillQnAEventAsync(
                                        queryResults,
                                        turnContext,
                                        telemetryProperties,
                                        telemetryMetrics,
                                        cancellationToken)
                                    .ConfigureAwait(false);
    
                // Add new property
                eventData.Properties.Add("MyImportantProperty", "myImportantValue");
    
                // Log QnAMessage event
                TelemetryClient.TrackEvent(
                                QnATelemetryConstants.QnaMsgEvent,
                                eventData.Properties,
                                eventData.Metrics
                                );
            }
    
        }
    }
    
  4. Modifique el bot para que use la nueva clase. En lugar de crear un objeto QnAMaker, creará un objeto MyQnAMaker en QnABot.cs:Modify your bot to use the new class, instead of creating a QnAMaker object you will create a MyQnAMaker object in QnABot.cs:

    var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
                {
                    KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                    EndpointKey = _configuration["QnAEndpointKey"],
                    Host = _configuration["QnAEndpointHostName"]
                },
                null,
                httpClient,
                _telemetryClient);
    
Visualización de los datos de telemetría registrados desde la nueva propiedad MyImportantPropertyViewing telemetry data logged from the new property MyImportantProperty

Después de ejecutar el bot en el emulador, puede ver los resultados en Application Insights haciendo lo siguiente:After running your bot in the Emulator you can view the results in Application Insights by doing the following:

  1. Vuelva al explorador que tiene activa la vista Registros (Analytics) .Switch back to your browser that has the Logs (Analytics) view active.

  2. Escriba la siguiente consulta de Kusto y seleccione Ejecutar.Enter the following Kusto query and then select Run. Esto le dará el número de veces que se ejecutó la nueva propiedad:This will give a count of the number of times the new property was executed:

    customEvents
    | where name == 'QnaMessage'
    | extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
    | summarize count() by MyImportantProperty
    
  3. Para mostrar los detalles en lugar del recuento, quite la última línea y vuelva a ejecutar la consulta:To show details instead of the count remove the last line and re-run the query:

    customEvents
    | where name == 'QnaMessage'
    | extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
    

Adición de nuevos eventos con propiedades personalizadasAdding new events with custom properties

Si necesita registrar datos en un evento diferente al de QnaMessage, puede crear su propio evento personalizado con sus propiedades.If you need to log data to a different event than QnaMessage, you can create your own custom event with its own properties. Para ello, agregaremos código al final de la clase MyQnAMaker, tal y como se indica a continuación:To do this, we will add code to the end of the MyQnAMaker class as follows:

public class MyQnAMaker : QnAMaker
{
    ...

    // Create second event.
    var secondEventProperties = new Dictionary<string, string>();

    // Create new property for the second event.
    secondEventProperties.Add(
                        "MyImportantProperty2",
                        "myImportantValue2");

    // Log secondEventProperties event
    TelemetryClient.TrackEvent(
                    "MySecondEvent",
                    secondEventProperties);

}

Panel de Application InsightsThe Application Insights dashboard

Cada vez que cree un recurso de Application Insights en Azure, se creará un nuevo panel y se le asociará automáticamente.Anytime you create an Application Insights resource in Azure, a new dashboard will automatically be created and associated with it. Puede ver ese panel seleccionando el botón situado en la parte superior de la hoja de Application Insights, etiquetado como Panel de la aplicación.You can see that dashboard by selecting the button at the top of your Application Insights blade, labeled Application Dashboard.

Vínculo Panel de la aplicación

Como alternativa, para ver los datos, vaya a Azure Portal.Alternatively, to view the data, go to the Azure portal. Haga clic en Panel a la izquierda y seleccione el panel que desee en la lista desplegable.Click Dashboard on the left, then select the dashboard you want from the drop-down.

Allí puede ver información predeterminada sobre el rendimiento del bot y sobre cualquier consulta adicional que haya anclado al panel.There you'll see some default information about your bot performance and any additional queries that you've pinned to your dashboard.

Información adicionalAdditional Information