Adición de telemetría al bot

SE APLICA A: SDK v4

El registro de telemetría permite a las aplicaciones de bot enviar datos de eventos a servicios de telemetría, como Application Insights. La telemetría ofrece información sobre el bot mostrando qué características se usan más, detecta el comportamiento no deseado y ofrece visibilidad sobre la disponibilidad, el rendimiento y el uso.

En este artículo se describe cómo implementar la telemetría en el bot mediante Application Insights. En este artículo se describe:

• El código necesario para conectar la telemetría en el bot y conectarse a Application Insights.
• Cómo habilitar la telemetría en los cuadros de diálogo del bot.
• Cómo habilitar la telemetría para capturar datos de uso de otros servicios, como los servicios de Azure AI.
• Visualización de los datos de telemetría en Application Insights.

Importante

Para un bot regional que pueda recopilar información de identificación personal (PII) en la telemetría, el recurso de Application Insights y el recurso de Azure Bot deben estar en la misma región con el bot. Si los recursos están en regiones diferentes, el PII podría dejar la región geográfica del bot.

Requisitos previos

C#

• Código de ejemplo de CoreBot
• Código de ejemplo de Application Insights
• Una suscripción a Microsoft Azure
• Una clave de Application Insights
• Experiencia con Application Insights
• git

Nota:

El código de ejemplo de Application Insights se compiló a partir del código de ejemplo de CoreBot. Este artículo le guía a través de la modificación del código de ejemplo de CoreBot para incorporar datos de telemetría. Si va a seguir en Visual Studio, tendrá el código de ejemplo de Application Insights en el momento en que haya terminado.

JavaScript

• Código de ejemplo de CoreBot
• Código de ejemplo de Application Insights
• Una suscripción a Microsoft Azure
• Una clave de Application Insights
• Experiencia con Application Insights
• Visual Studio Code
• Node.js versión 10.14 o posterior. Use el comando node --version para determinar la versión del nodo que tiene.
• Bot Framework Emulator

Nota:

El código de ejemplo de Application Insights se compiló a partir del código de ejemplo de CoreBot. Este artículo le guía a través de la modificación del código de ejemplo de CoreBot para incorporar datos de telemetría. Si va a seguir en Visual Studio Code, tendrá el código de ejemplo de Application Insights en el momento en que haya terminado.

Habilitación de la telemetría en el bot

C#

Este artículo comienza desde la aplicación de ejemplo CoreBot y agrega el código necesario para integrar la telemetría en cualquier bot. Esto permitirá a Application Insights empezar a realizar el seguimiento de solicitudes.

Importante

Si no ha configurado la cuenta de Application Insights y ha creado la clave de Application Insights, hála antes de continuar.

1. Abra la aplicación de ejemplo CoreBot en Visual Studio.

2. Agregue el paquete NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Para más información sobre el uso de NuGet, consulte Instalación y administración de paquetes en Visual Studio:

3. Incluya las siguientes instrucciones en 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;
   

   Sugerencia

   Si va a seguir el código de ejemplo de CoreBot, observará que la instrucción Microsoft.Bot.Builder.Integration.AspNet.Core using ya existe en el ejemplo coreBot.

4. Incluya el siguiente código en el método ConfigureServices() en Startup.cs. Esto hará que los servicios de telemetría estén disponibles para su bot a través de la inserción de dependencias (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>();
       ...
   }
   

   Sugerencia

   Si va a seguir al actualizar el código de ejemplo de CoreBot, observará que services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); ya existe.

5. Indique al adaptador que use el código de middleware que se agregó al método ConfigureServices(). Esto se hace con AdapterWithErrorHandler.cs el parámetro TelemetryInitializerMiddleware telemetryInitializerMiddleware en la lista de parámetros del constructor y la Use(telemetryInitializerMiddleware); instrucción en el constructor como se muestra aquí:

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

6. También deberá agregar Microsoft.Bot.Builder.Integration.ApplicationInsights.Core a la lista de instrucciones using en AdapterWithErrorHandler.cs.

7. Agregue la clave de instrumentación de Application Insights a su archivo appsettings.json. El appsettings.json archivo contiene metadatos sobre los servicios externos que usa el bot mientras se ejecuta. Por ejemplo, la conexión y los metadatos de los servicios de Cosmos DB, Application Insights y Azure AI se almacenan allí. La adición al archivo appsettings.json debe estar en este formato:

   {
       "MicrosoftAppId": "",
       "MicrosoftAppPassword": "",
       "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.

En este momento, se realiza el trabajo preliminar para habilitar la telemetría mediante Application Insights. Puede ejecutar el bot localmente mediante el emulador 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 de ejecución general.

Habilitación de la telemetría en los cuadros de diálogo del bot

Al agregar un nuevo diálogo a cualquier elemento ComponentDialog, heredará el objeto Microsoft.Bot.Builder.IBotTelemetryClient de su diálogo primario. Por ejemplo, en la aplicación de ejemplo CoreBot, todos los diálogos se agregan a MainDialog, que es componentDialog. Una vez establecida la propiedad TelemetryClient en MainDialog, todos los diálogos agregados a él heredarán automáticamente telemetryClient de él, por lo que no es necesario establecer explícitamente al agregar diálogos.

Siga los pasos que se indican a continuación para actualizar el ejemplo de CoreBot:

1. En MainDialog.cs, actualice la lista de parámetros del constructor para incluir el parámetro IBotTelemetryClient y, a continuación, establezca la propiedad TelemetryClient de MainDialog en ese valor, tal como se muestra en el siguiente fragmento de código:

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

Sugerencia

Si va a seguir y actualiza el código de ejemplo de CoreBot, puede consultar el código de ejemplo de Application Insights si tiene algún problema.

La telemetría ahora se agrega a los diálogos del bot. Si ejecuta el bot ahora, debería ver las cosas que se registran en Application Insights; Sin embargo, si tiene alguna tecnología integrada, como un servicio de Azure AI, deberá agregar también el TelemetryClient elemento a ese código.

JavaScript

Este artículo comienza con la aplicación de ejemplo CoreBot y agrega el código necesario para integrar la telemetría en cualquier bot. Esto permitirá a Application Insights empezar a realizar el seguimiento de solicitudes.

Importante

Si no ha configurado la cuenta de Application Insights y ha creado la clave de Application Insights, hála antes de continuar.

1. Abra la aplicación de ejemplo CoreBot en Visual Studio Code.

2. Agregue la clave de Application Insights al .env archivo: InstrumentationKey=<EnterInstrumentationKeyHere>. El .env archivo contiene metadatos sobre los servicios externos que usa el bot mientras se ejecuta. Por ejemplo, la conexión y los metadatos de los servicios de Application Insights y Azure AI se almacenan allí. La adición al archivo .env debe estar en este formato:

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

   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.

3. Agregue una referencia a los módulos ApplicationInsightsTelemetryClient y TelemetryInitializerMiddleware que se encuentran en botbuilder-applicationinsights Bot Framework SDK. Para ello, agregue el código siguiente a partir de la parte superior de index.js, justo después del código para importar los paquetes necesarios:

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

   Sugerencia

   Los ejemplos de bots de JavaScript usan Node.js, que sigue al sistema de módulos CommonJS y la función integrada require para incluir módulos que existen en archivos independientes.

4. Cree una nueva función al final del nombre getTelemetryClient que toma la clave de index.js instrumentación como parámetro y devuelve un cliente de telemetría mediante el ApplicationInsightsTelemetryClient módulo al que se hace referencia anteriormente. Este cliente de telemetría es donde se enviarán los datos de telemetría, en este 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. A continuación, debe agregar el middleware de telemetría a la canalización de middleware del adaptador. Para ello, agregue el código siguiente, empezando justo después del código de control de errores:

   
   // 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. Para que el cuadro de diálogo notifique los datos de telemetría, debe telemetryClient coincidir con el usado para el middleware de telemetría, es decir, 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. Después de crear el objeto de servidor web HTTP restify, indique que use el bodyParser controlador.

       }
       return new NullTelemetryClient();
   }
   

   Sugerencia

   Esto usa la función restifybodyParser. restify es un "marco de servicio web de Node.js optimizado para compilar servicios web RESTful semánticamente correctos listos para su uso en producción a escala. restify optimiza la introspección y el rendimiento, y se usa en algunas de las implementaciones de Node.js más grandes en la Tierra". Para obtener más información, consulte el sitio web restify .

   Node.js sigue el sistema de módulos CommonJS y usa la función integrada require para incluir módulos que existen en archivos independientes.

En este momento, se realiza el trabajo preliminar para habilitar la telemetría mediante Application Insights. Puede ejecutar el bot localmente mediante el emulador 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 de ejecución general.

Habilitar o deshabilitar el registro de eventos de actividad e información personal

C#

Habilitar o deshabilitar el registro de actividad

De forma predeterminada, TelemetryInitializerMiddleware usará TelemetryLoggerMiddleware para registrar la telemetría cuando el bot envía o recibe actividades. El registro de actividades crea registros de eventos personalizados en el recurso de Application Insights. Si lo desea, puede deshabilitar el registro de eventos de actividad estableciendo logActivityTelemetry en false al TelemetryInitializerMiddleware registrarlo en 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);
            });
    ...
}

Habilitar o deshabilitar el registro de información personal

De forma predeterminada, si el registro de actividad está habilitado, algunas propiedades de las actividades entrantes o salientes se excluyen del registro, ya que es probable que contengan información personal, como el nombre de usuario y el texto de la actividad. Puede optar por incluir estas propiedades en el registro realizando el siguiente cambio en Startup.cs al registrar 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);
            });
    ...
}

A continuación, veremos lo que debe incluirse para agregar la funcionalidad de telemetría a los diálogos. Esto le permitirá obtener información adicional como, por ejemplo, qué diálogos ejecutar y las estadísticas de cada uno.

JavaScript

Habilitar o deshabilitar el registro de actividad

De forma predeterminada, TelemetryInitializerMiddleware usará TelemetryLoggerMiddleware para registrar la telemetría cuando el bot envíe o reciba actividades. El registro de actividades crea registros de eventos personalizados en el recurso de Application Insights. Si lo desea, puede deshabilitar el registro de eventos de actividad estableciendo logActivityTelemetry en false al TelemetryInitializerMiddleware registrarlo en index.js.

El siguiente fragmento de código procede del 21.corebot-app-insightsejemplo y muestra la llamada 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();

El fragmento de código siguiente muestra el cambio necesario en el ejemplo 21.corebot-app-insights, en la llamada a TelemetryInitializerMiddleware para deshabilitar el registro de actividad:

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

Habilitar o deshabilitar el registro de información personal

Cuando se habilita el registro de actividad, algunas propiedades de las actividades entrantes o salientes se excluyen del registro de forma predeterminada, ya que es probable que contengan información personal, como el nombre de usuario y el texto de la actividad. Puede elegir incluir estas propiedades en el registro cambiando el logPersonalInformation parámetro de false a true al registrar en TelemetryLoggerMiddleware 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();

A continuación, veremos lo que debe incluirse para agregar la funcionalidad de telemetría a los diálogos. Esto le permitirá obtener información adicional como, por ejemplo, qué diálogos ejecutar y las estadísticas de cada uno.

Habilitar la telemetría para capturar datos de uso de otros servicios como Luis y QnA Maker

Nota:

Azure AI QnA Maker se retirará el 31 de marzo de 2025. A partir del 1 de octubre de 2022, no podrá crear nuevos recursos o bases de conocimiento de QnA Maker. Ya hay disponible una versión más reciente de la funcionalidad de preguntas y respuestas como parte de Lenguaje de Azure AI.

La respuesta a preguntas personalizadas, una característica de Lenguaje de Azure AI, es la versión actualizada del servicio QnA Maker. Para obtener más información sobre la compatibilidad con preguntas y respuestas en Bot Framework SDK, consulte Comprensión del lenguaje natural.

Nota:

Reconocimiento del lenguaje (LUIS) se retirará el 1 de octubre de 2025. A partir del 1 de abril de 2023, no podrás crear nuevos recursos de LUIS. Hay disponible una versión más reciente de las funcionalidades de reconocimiento del lenguaje como parte del Lenguaje de Azure AI.

Reconocimiento del lenguaje conversacional (CLU), una característica del lenguaje de Azure AI, es la versión actualizada de LUIS. Para obtener más información sobre la compatibilidad con reconocimiento del lenguaje en Bot Framework SDK, consulte reconocimiento natural del lenguaje.

C#

A continuación, implementaremos la funcionalidad de telemetría en el servicio luis. El servicio LUIS tiene disponible el registro de telemetría integrado, por lo que es poco necesario hacer para empezar a obtener datos de telemetría de LUIS. Si está interesado en habilitar la telemetría en un bot habilitado para QnA Maker, consulte Incorporación de telemetría al bot de QnA Maker.

1. El parámetro IBotTelemetryClient telemetryClient es necesario en el constructor FlightBookingRecognizer de FlightBookingRecognizer.cs:

   public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
   

2. A continuación, habilite cuando telemetryClient cree LuisRecognizer en el FlightBookingRecognizer constructor . Para ello, agregue telemetryClient como nuevo 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);
   }
   

En este caso, debe tener un bot funcional que registre los datos de telemetría en Application Insights. Puede usar Bot Framework Emulator para ejecutar el bot localmente. No debería observar ningún cambio en el comportamiento del bot, pero este estará registrando información en Application Insights. Interactúe con el bot mediante el envío de varios mensajes y, en la sección siguiente, revisaremos los resultados de telemetría en Application Insights.

Para más información sobre cómo probar y depurar el bot, puede consultar los siguientes artículos:

• Depuración de un bot
• Directrices de prueba y depuración
• Depuración con el emulador

JavaScript

A continuación, implementaremos la funcionalidad de telemetría en el servicio luis. El servicio LUIS tiene disponible el registro de telemetría integrado, por lo que es poco necesario hacer para empezar a obtener datos de telemetría de LUIS.

Para habilitar el cliente de telemetría en el reconocedor de LUIS:

1. Abrir FlightBookingRecognizer.js

2. Pase el telemetryClient parámetro al FlightBookingRecognizer constructor:

   constructor(config, telemetryClient) {
   

3. Establezca el telemetryClient campo del recognizerOptions objeto en la telemetryClient propiedad que se pasa al FlightBookingRecognizer constructor, una vez hecho el constructor aparecerá como sigue:

   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. Por último, debe incluir al telemetryClient crear una instancia de FlightBookingRecognizer en index.js:

   const memoryStorage = new MemoryStorage();
   

Eso es todo; Debe tener un bot funcional que registre los datos de telemetría en Application Insights. Puede usar Bot Framework Emulator para ejecutar el bot localmente. No debería observar ningún cambio en el comportamiento del bot, pero este estará registrando información en Application Insights. Para interactuar con el bot, envíe varios mensajes y en la sección siguiente se describe cómo revisar los resultados de telemetría en Application Insights.

Para más información sobre cómo probar y depurar el bot, puede consultar los siguientes artículos:

• Depuración de un bot
• Directrices de prueba y depuración
• Depuración con el emulador

Visualización de los datos de telemetría en Application Insights

Application Insights supervisa la disponibilidad, el rendimiento y el uso de la aplicación del bot, tanto si está hospedada en la nube como en un entorno local. Usa la potente plataforma de análisis de datos en Azure Monitor para proporcionarle información detallada sobre las operaciones de la aplicación y diagnosticar errores sin esperar a que un usuario los notifique. Hay varias maneras de ver los datos de telemetría recopilados por Application Insights. Dos de los métodos principales son mediante consultas y a través del panel.

Consulta de los datos de telemetría en Application Insights mediante consultas de Kusto

Utilice esta sección como punto de partida para aprender a usar las consultas de registro en Application Insights. Muestra dos consultas útiles y proporciona vínculos a otra documentación con información adicional.

Para consultar los datos

1. Vaya a Azure Portal.

2. Para ir a la página de Application Insights, seleccione Supervisar y, a continuación , Aplicaciones y después busque allí.

3. Una vez en Application Insights, seleccione Registros (Analytics) .

   

4. Se abrirá la ventana de consulta. Escriba la siguiente consulta y seleccione Ejecutar:

   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. Esto devolverá el porcentaje de diálogos en cascada que se ejecutan hasta completarse.

   

Sugerencia

Puede anclar cualquier consulta al panel de Application Insights seleccionando el botón situado en la parte superior derecha de la hoja Registros (Analytics). Simplemente seleccione el panel al que desea anclarlo y estará disponible la próxima vez que visite ese panel.

Panel de Application Insights

Cada vez que cree un recurso de Application Insights en Azure, se creará un nuevo panel y se le asociará automáticamente. 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.

Como alternativa, para ver los datos, vaya a Azure Portal. Seleccione Panel a la izquierda y, a continuación, seleccione el panel que desee en la lista desplegable.

Allí puede ver información predeterminada sobre el rendimiento del bot y sobre cualquier consulta adicional que haya anclado al panel.

Información adicional

• Incorporación de telemetría al bot de QnA Maker
• ¿Qué es Application Insights?
• Uso de Búsqueda en Application Insights
• Creación de paneles de indicadores clave de rendimiento (KPI) personalizados con Azure Application Insights