Добавление данных телеметрии в бот

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

Ведение журнала телеметрии позволяет приложениям бота отправлять данные о событиях в службы телеметрии, такие как Application Insights. Телеметрия предоставляет аналитические сведения о боте, показывая, какие функции используются чаще всего, обнаруживает нежелательное поведение и обеспечивает видимость доступности, производительности и использования.

В этой статье описывается реализация телеметрии в боте с помощью Application Insights. В этой статье рассматриваются следующие вопросы:

• Код, необходимый для подключения телеметрии в боте и подключения к Application Insights.
• Включение телеметрии в диалоговых окнах бота.
• Как включить данные телеметрии для сбора данных об использовании из других служб, таких как службы искусственного интеллекта Azure.
• Визуализация данных телеметрии в Application Insights.

Внимание

Для регионального бота, который может собирать персональные данные (PII) в телеметрии, ресурс Application Insights и ресурс Azure Bot должны находиться в одном регионе с ботом. Если ресурсы находятся в разных регионах, личные данные могут оставить географический регион бота.

Необходимые компоненты

C#

• Пример кода CoreBot.
• Пример кода Application Insights.
• Подписка на Microsoft Azure.
• Ключ Application Insights.
• Опыт работы с Application Insights.
• git

Примечание.

Пример кода Application Insights основан на примере кода CoreBot. В этой статье показано, как изменить пример кода CoreBot для включения телеметрии. Если вы следуют вместе в Visual Studio, вы получите пример кода Application Insights к моменту завершения.

JavaScript

• Пример кода CoreBot.
• Пример кода Application Insights.
• Подписка на Microsoft Azure.
• Ключ Application Insights.
• Опыт работы с Application Insights.
• Visual Studio Code
• Node.js версии 10.14 или более поздней. Используйте команду node --version , чтобы определить версию узла, который у вас есть.
• Bot Framework Emulator.

Примечание.

Пример кода Application Insights основан на примере кода CoreBot. В этой статье показано, как изменить пример кода CoreBot для включения телеметрии. Если вы следуют вместе с Visual Studio Code, вы получите пример кода Application Insights к моменту завершения.

Включение телеметрии в боте

C#

Эта статья начинается с примера приложения CoreBot и добавляет код, необходимый для интеграции телеметрии в любой бот. Так Application Insights сможет отслеживать запросы.

Внимание

Если вы не настроите учетную запись Application Insights и создали ключ Application Insights, сделайте это, прежде чем продолжить.

1. Откройте пример приложения CoreBot в Visual Studio.

2. Добавление пакета NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Подробные сведения об использовании NuGet см. в руководстве по установке пакетов и управлении ими в Visual Studio.

3. Добавьте следующие инструкции в 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;
   

   Совет

   Если вы следуете вместе, обновив пример кода CoreBot, вы заметите, что инструкция using для Microsoft.Bot.Builder.Integration.AspNet.Core уже существует в примере CoreBot.

4. Включите следующий код в метод ConfigureServices() в Startup.cs. Так службы телеметрии станут доступными для бота путем внедрения зависимостей:

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

   Совет

   Если вы следуете вместе, обновив пример кода CoreBot, вы заметите, что services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); уже существует.

5. Настройте адаптер на использование кода ПО промежуточного слоя, который был добавлен в метод ConfigureServices(). Это AdapterWithErrorHandler.cs можно сделать с помощью параметра TelemetryInitializerMiddleware telemetryInitializerMiddleware в списке параметров конструктора и Use(telemetryInitializerMiddleware); инструкцию в конструкторе, как показано здесь:

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

6. Вам также потребуется добавить Microsoft.Bot.Builder.Integration.ApplicationInsights.Core в список инструкций using.AdapterWithErrorHandler.cs

7. Добавьте ключ инструментирования Application Insights в файл appsettings.json. Файл appsettings.json содержит метаданные о внешних службах, которые бот использует во время выполнения. Например, подключение и метаданные служб ИИ Azure Cosmos DB, Application Insights и метаданные хранятся там. Формат добавляемого в файл appsettings.json ключа должен быть таким:

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

   Примечание.

   Сведения о ключе инструментирования Application см. в статье о ключах Application Insights.

На этом этапе выполняется предварительная работа по включению телеметрии с помощью Application Insights. Вы можете запустить бот локально с помощью эмулятора, а затем перейти в Application Insights, чтобы узнать, что регистрируется в журнале, например время отклика, общее состояние приложения и общие сведения о выполнении.

Включение телеметрии в диалоговых окнах бота

При добавлении нового диалога в любой класс ComponentDialog он наследует Microsoft.Bot.Builder.IBotTelemetryClient из родительского диалога. Например, в примере приложения CoreBot все диалоги добавляются в MainDialog, который является компонентом ComponentDialog. После задания свойства TelemetryClient для MainDialog все диалоги, добавленные в него, автоматически наследуют данные телеметрииClient, поэтому при добавлении диалоговых окон не требуется явно задавать.

Чтобы обновить код CoreBot, сделайте следующее:

1. Обновите список параметров конструктора в MainDialog.cs, включив в него параметр IBotTelemetryClient, а затем в MainDialog установите для свойства TelemetryClient это же значение, как показано в следующем фрагменте кода:

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

Совет

Если вы следуете вместе и обновляете пример кода CoreBot, вы можете обратиться к примеру кода Application Insights, если у вас возникли проблемы.

Теперь данные телеметрии добавляются в диалоговые окна бота. Если вы запускаете бот сейчас, вы увидите, что выполняется вход в Application Insights; Однако если у вас есть интегрированная технология, например служба ИИ Azure, вам также потребуется добавить этот TelemetryClient код.

JavaScript

Эта статья начинается с примера приложения CoreBot и добавляет код, необходимый для интеграции телеметрии в любой бот. Так Application Insights сможет отслеживать запросы.

Внимание

Если вы не настроите учетную запись Application Insights и создали ключ Application Insights, сделайте это, прежде чем продолжить.

1. Откройте пример приложения CoreBot в Visual Studio Code.

2. Добавьте ключ Application Insights в .env файл: InstrumentationKey=<EnterInstrumentationKeyHere> Файл .env содержит метаданные о внешних службах, которые бот использует во время выполнения. Например, подключение к службам Application Insights и службам искусственного интеллекта Azure и метаданные хранятся там. Формат добавляемого в файл .env ключа должен быть таким:

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

   Примечание.

   Сведения о ключе инструментирования Application см. в статье о ключах Application Insights.

3. Добавьте ссылку на модули ApplicationInsightsTelemetryClient и TelemetryInitializerMiddleware расположенные в botbuilder-applicationinsights пакете SDK Bot Framework. Для этого добавьте следующий код, начиная с верхней части index.jsкода, сразу после импорта необходимых пакетов:

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

   Совет

   Примеры ботов JavaScript используют Node.js, которая следует системе модулей CommonJS и встроенной require функции для включения модулей, существующих в отдельных файлах.

4. Создайте новую функцию в конце index.js имени getTelemetryClient , которая принимает ключ инструментирования в качестве параметра и возвращает клиент телеметрии с помощью ApplicationInsightsTelemetryClient модуля, на который вы ссылались ранее. Этот клиент телеметрии находится в том месте, в котором будут отправляться данные телеметрии, в этом случае 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. Затем необходимо добавить ПО промежуточного слоя телеметрии в конвейер ПО промежуточного слоя адаптера. Для этого добавьте следующий код, начиная с кода обработки ошибок:

   
   // 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. Чтобы диалоговое окно сообщал данные телеметрии, оно telemetryClient должно совпадать с тем, который используется для по промежуточного слоя телеметрии, то есть 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. После создания объекта restify веб-сервера HTTP указать ему использовать bodyParser обработчик.

       }
       return new NullTelemetryClient();
   }
   

   Совет

   Для этого используется функция restifybodyParser. restify — это платформа веб-службы Node.js, оптимизированная для создания семантических правильных веб-служб RESTful, готовых к использованию в рабочей среде. оптимизируйте оптимизацию для интроспекции и производительности и используется в некоторых из крупнейших развертываний Node.js на Земле». Дополнительные сведения см. на веб-сайте restify .

   Node.js следует системе модулей CommonJS и использует встроенную require функцию для включения модулей, существующих в отдельных файлах.

На этом этапе выполняется предварительная работа по включению телеметрии с помощью Application Insights. Вы можете запустить бот локально с помощью эмулятора, а затем перейти в Application Insights, чтобы узнать, что регистрируется в журнале, например время отклика, общее состояние приложения и общие сведения о выполнении.

Включение или отключение ведения журнала событий и личных сведений

C#

Включение или отключение ведения журнала действий

По умолчанию TelemetryInitializerMiddleware будет использовать TelemetryLoggerMiddleware для регистрации данных телеметрии, когда бот отправляет или получает действия. Ведение журнала действий создает пользовательские журналы событий в ресурсе Application Insights. Если вы хотите, можно отключить ведение журнала событий действий, установив logActivityTelemetry значение false при TelemetryInitializerMiddleware регистрации в 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);
            });
    ...
}

Включение или отключение ведения журнала персональных данных

По умолчанию, если ведение журнала действий включено, некоторые свойства входящих и исходящих действий исключаются из ведения журнала, так как они, скорее всего, содержат личную информацию, например имя пользователя и текст действия. Вы можете включить сохранение этих свойств в журнал, внеся следующие изменения в Startup.cs при регистрации 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);
            });
    ...
}

Далее мы увидим, что необходимо включить для добавления функций телеметрии в диалоговые окна. Так вы сможете получать дополнительные сведения о запущенных диалогах, а также собирать статистику по каждому из них.

JavaScript

Включение или отключение ведения журнала действий

По умолчанию используется TelemetryInitializerMiddleware TelemetryLoggerMiddleware для записи данных телеметрии, когда бот отправляет или получает действия. Ведение журнала действий создает пользовательские журналы событий в ресурсе Application Insights. Если вы хотите, можно отключить ведение журнала событий действий, установив logActivityTelemetry значение false при TelemetryInitializerMiddleware регистрации в index.js.

Следующий фрагмент кода получен из примера 21.corebot-app-insightsи показывает вызов 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();

В приведенном ниже фрагменте кода показано изменение, необходимое в примере 21.corebot-app-insights, в вызове для TelemetryInitializerMiddleware отключения ведения журнала действий:

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

Включение или отключение ведения журнала персональных данных

Если ведение журнала действий включено, некоторые свойства входящих и исходящих действий по умолчанию исключаются из ведения журнала, так как они, скорее всего, содержат личную информацию, например имя пользователя и текст действия. Вы можете включить эти свойства в ведение журнала, изменив logPersonalInformation TelemetryLoggerMiddleware параметр с false true момента регистрации в 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();

Далее мы увидим, что необходимо включить для добавления функций телеметрии в диалоговые окна. Так вы сможете получать дополнительные сведения о запущенных диалогах, а также собирать статистику по каждому из них.

Настройка телеметрии для сбора данных об использовании из других служб, например LUIS и QnA Maker

Примечание.

Azure AI QnA Maker будет прекращен 31 марта 2025 г. С 1 октября 2022 г. вы не сможете создавать новые ресурсы или базы знаний QnA Maker. Новая версия вопроса и возможности ответа теперь доступна как часть языка искусственного интеллекта Azure.

Пользовательский ответ на вопросы, компонент языка искусственного интеллекта Azure, — это обновленная версия службы QnA Maker. Дополнительные сведения о поддержке вопросов и ответов в пакете SDK Bot Framework см. в разделе "Распознавание естественного языка".

Примечание.

Распознавание речи (LUIS) будет прекращен 1 октября 2025 года. Начиная с 1 апреля 2023 года вы не сможете создавать новые ресурсы LUIS. Новая версия распознавания речи теперь доступна как часть языка ИИ Azure.

Распознавание речи (CLU) — это обновленная версия LUIS. Дополнительные сведения о поддержке распознавания речи в пакете SDK Bot Framework см. в разделе "Распознавание естественного языка".

C#

Далее мы реализуем функции телеметрии в службе LUIS. Служба LUIS имеет встроенную возможность ведения журнала телеметрии, поэтому для начала получения данных телеметрии из LUIS не требуется. Если вы хотите включить телеметрию в боте с поддержкой QnA Maker, см. статью "Добавление телеметрии в бот QnA Maker"

1. Параметр IBotTelemetryClient telemetryClient является обязательным в конструкторе FlightBookingRecognizer в FlightBookingRecognizer.cs:

   public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
   

2. Затем включите telemetryClient его при создании LuisRecognizer в конструкторе FlightBookingRecognizer . Для этого добавьте telemetryClient новый 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);
   }
   

Теперь у вас есть функциональный бот, который записывает данные телеметрии в Application Insights. Запустить бота локально можно с помощью Bot Framework Emulator. Вы не увидите изменений в поведении бота, но данные будут регистрироваться в Application Insights. Взаимодействуйте с ботом, отправляя несколько сообщений и в следующем разделе мы рассмотрим результаты телеметрии в Application Insights.

Сведения о тестировании и отладке бота см. в таких статьях:

• Отладка бота
• Рекомендации по тестированию и отладке
• Отладка ботов с помощью эмулятора

JavaScript

Далее мы реализуем функции телеметрии в службе LUIS. Служба LUIS имеет встроенную возможность ведения журнала телеметрии, поэтому для начала получения данных телеметрии из LUIS не требуется.

Чтобы включить клиент телеметрии в распознаватель LUIS, выполните следующие действия.

1. Открыть FlightBookingRecognizer.js

2. telemetryClient Передайте параметр конструкторуFlightBookingRecognizer:

   constructor(config, telemetryClient) {
   

3. telemetryClient Задайте поле recognizerOptions объекта telemetryClient свойству, передаваемого в FlightBookingRecognizer конструктор, после завершения конструктора отобразится следующим образом:

   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. И, наконец, необходимо включить telemetryClient при создании экземпляра FlightBookingRecognizer в index.js:

   const memoryStorage = new MemoryStorage();
   

Ну вот; У вас должен быть функциональный бот, который записывает данные телеметрии в Application Insights. Запустить бота локально можно с помощью Bot Framework Emulator. Вы не увидите изменений в поведении бота, но данные будут регистрироваться в Application Insights. Взаимодействие с ботом путем отправки нескольких сообщений, а в следующем разделе описывается, как просмотреть результаты телеметрии в Application Insights.

Сведения о тестировании и отладке бота см. в таких статьях:

• Отладка бота
• Рекомендации по тестированию и отладке
• Отладка ботов с помощью эмулятора

Отображение данных телеметрии в Application Insights

Application Insights отслеживает доступность, производительность и использование бота независимо от размещения (в облачной или локальной среде). Она использует мощную платформу анализа данных в Azure Monitor, чтобы получить подробные сведения об операциях приложения и диагностировать ошибки, не ожидая, когда пользователь сообщит о них. Данные телеметрии, собираемые Application Insights, можно просматривать несколькими способами: с помощью запросов и панели мониторинга.

Получение данных телеметрии в Application Insights с помощью запросов Kusto

В этом разделе описано, как использовать запросы журналов в Application Insights с помощью двух запросов, а также предоставлены ссылки на другую документацию с дополнительными сведениями.

Чтобы запросить данные:

1. Перейдите на портал Azure.

2. Чтобы перейти на страницу Application Insights, выберите "Монитор", а затем "Приложения" и найдите его там.

3. После входа в Application Insights выберите logs (Analytics).

   

4. Откроется окно "Запрос". Введите следующий запрос и нажмите Запуск:

   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. Отобразится процент каскадных диалоговых окон, которые выполнялись до завершения.

   

Совет

Любой запрос можно закрепить на панели мониторинга Application Insights, нажав на кнопку в верхней правой части колонки Журналы (Analytics). Просто выберите нужную панель мониторинга, и вы сможете выбрать этот запрос при ее следующем открытии.

Панель мониторинга Application Insights

Когда вы создаете ресурс Application Insights в Azure, автоматически создается и связанная панель мониторинга. Эту панель мониторинга можно просмотреть, нажав кнопку Панель мониторинга приложений в верхней части колонки Application Insights.

Просмотреть данные можно также на портале Azure. Выберите панель мониторинга слева, а затем выберите нужную панель мониторинга в раскрывающемся списке.

Здесь вы увидите некоторые стандартные сведения о производительности бота и дополнительные запросы, которые вы закрепили на панели мониторинга.

Дополнительная информация

• Добавление телеметрии в бот QnA Maker
• Что такое Azure Application Insights?
• Поиск в Application Insights
• Создание настраиваемых панелей мониторинга ключевых показателей эффективности с помощью Azure Application Insights