Примечание
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4
Ведение журнала телеметрии позволяет приложениям бота отправлять данные о событиях в службы телеметрии, такие как Application Insights. Телеметрия предоставляет аналитические сведения о боте, показывая, какие функции используются чаще всего, обнаруживает нежелательное поведение и обеспечивает видимость доступности, производительности и использования.
В этой статье описывается реализация телеметрии в боте с помощью Application Insights. В этой статье рассматриваются следующие вопросы:
- Код, необходимый для подключения телеметрии в боте и подключения к Application Insights.
- Включение телеметрии в диалоговых окнах бота.
- Как включить телеметрию для сбора данных об использовании из других служб, таких как службы Azure для искусственного интеллекта.
- Визуализация данных телеметрии в Application Insights.
Внимание
Для регионального бота, который может собирать персональные данные (PII) в телеметрии, ресурс Application Insights и ресурс Azure Bot должны находиться в одном регионе с ботом. Если ресурсы находятся в разных регионах, личные данные могут оставить географический регион бота.
Необходимые компоненты
- Пример кода CoreBot.
- Пример кода Application Insights.
- Подписка на Microsoft Azure.
- Ключ Application Insights.
- Опыт работы с Application Insights.
- Git
Примечание.
Пример кода Application Insights основан на примере кода CoreBot. В этой статье показано, как изменить пример кода CoreBot для включения телеметрии. Если вы следуют вместе в Visual Studio, вы получите пример кода Application Insights к моменту завершения.
Включение телеметрии в боте
Эта статья начинается с примера приложения CoreBot и добавляет код, необходимый для интеграции телеметрии в любой бот. Так Application Insights сможет отслеживать запросы.
Внимание
Если вы не настроили учетную запись Application Insights и не создали ключ Application Insights, сделайте это, прежде чем продолжить.
Откройте пример приложения CoreBot в Visual Studio.
Добавьте пакет NuGet
Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
. Подробные сведения об использовании NuGet см. в руководстве по установке пакетов и управлении ими в Visual Studio.Добавьте следующие утверждения в
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.Включите следующий код в метод
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>();
уже существует.Настройте адаптер на использование кода ПО промежуточного слоя, который был добавлен в метод
ConfigureServices()
. Сделайте это вAdapterWithErrorHandler.cs
с использованием параметра TelemetryInitializerMiddleware telemetryInitializerMiddleware в списке параметров конструктора и инструкциейUse(telemetryInitializerMiddleware);
в конструкторе, как показано здесь:public AdapterWithErrorHandler(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger, TelemetryInitializerMiddleware telemetryInitializerMiddleware, ConversationState conversationState = null) : base(configuration, logger) { ... Use(telemetryInitializerMiddleware); }
Вам также потребуется добавить
Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
в список директив using вAdapterWithErrorHandler.cs
.Добавьте ключ инструментирования Application Insights в файл
appsettings.json
. Файлappsettings.json
содержит метаданные о внешних службах, которые бот использует во время выполнения. Например, подключение и метаданные Cosmos DB, Application Insights и служб Azure AI хранятся там. Формат добавляемого в файлappsettings.json
ключа должен быть таким:{ "MicrosoftAppId": "", "MicrosoftAppPassword": "", "ApplicationInsights": { "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } }
Примечание.
Сведения о получении ключа инструментирования Application Insights можно найти в статье Ключи Application Insights.
На этом этапе выполняется предварительная работа по включению телеметрии с помощью Application Insights. Вы можете запустить бот локально с помощью эмулятора, а затем перейти в Application Insights, чтобы узнать, что регистрируется в журнале, например время отклика, общее состояние приложения и общие сведения о выполнении.
Включение телеметрии в диалоговых окнах бота
При добавлении нового диалога к любому элементу класса ComponentDialog, он наследует Microsoft.Bot.Builder.IBotTelemetryClient из родительского диалога. Например, в примере приложения CoreBot все диалоги добавляются в MainDialog, который является компонентом ComponentDialog. После задания свойства TelemetryClient для MainDialog все добавленные в него диалоги автоматически наследуют TelemetryClient, поэтому при добавлении диалогов его не требуется задавать явно.
Чтобы обновить пример CoreBot, выполните следующие шаги:
Обновите список параметров конструктора в
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
в этот код.
Включение или отключение ведения журнала событий и личных сведений
Включение или отключение ведения журнала действий
По умолчанию 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);
});
...
}
Далее мы увидим, что необходимо включить для добавления функций телеметрии в диалоговые окна. Так вы сможете получать дополнительные сведения о запущенных диалогах, а также собирать статистику по каждому из них.
Настройка телеметрии для сбора данных об использовании из других служб, например 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 см. в разделе "Распознавание естественного языка".
Далее мы реализуем функции телеметрии в службе LUIS. Служба LUIS предоставляет встроенное ведение журнала телеметрии, поэтому вам почти ничего не нужно делать, чтобы начать получать данные телеметрии из LUIS. Если вы хотите включить телеметрию в боте с поддержкой QnA Maker, см. статью "Добавление телеметрии в бот QnA Maker"
Параметр
IBotTelemetryClient telemetryClient
является обязательным в конструктореFlightBookingRecognizer
вFlightBookingRecognizer.cs
:public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
Затем при создании
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.
Сведения о тестировании и отладке бота см. в таких статьях:
Отображение данных телеметрии в Application Insights
Application Insights отслеживает доступность, производительность и использование бота независимо от размещения (в облачной или локальной среде). Она использует мощную платформу анализа данных в Azure Monitor, чтобы получить подробные сведения об операциях приложения и диагностировать ошибки, не ожидая, когда пользователь сообщит о них. Данные телеметрии, собираемые Application Insights, можно просматривать несколькими способами: с помощью запросов и панели мониторинга.
Получение данных телеметрии в Application Insights с помощью запросов Kusto
В этом разделе описано, как использовать запросы журналов в Application Insights Он демонстрирует два полезных запроса и предоставляет ссылки на другую документацию с дополнительной информацией.
Чтобы запросить данные:
Перейдите на портал Azure.
Чтобы перейти на страницу Application Insights, выберите "Монитор", а затем "Приложения" и найдите его там.
После входа в Application Insights выберите logs (Analytics).
Откроется окно "Запрос". Введите следующий запрос и нажмите Запуск:
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
Это вернёт процент каскадных диалогов, которые завершаются.
Совет
Любой запрос можно закрепить на панели Application Insights, нажав на кнопку в верхней правой части вкладки Журналы (Analytics). Просто выберите панель мониторинга, к которой хотите ее прикрепить, и она будет доступна в следующий раз, когда вы посетите эту панель.
Панель мониторинга Application Insights
Каждый раз, когда вы создаете ресурс Application Insights в Azure, к нему автоматически создается и привязывается новая панель мониторинга. Эту панель мониторинга можно просмотреть, нажав кнопку Панель мониторинга приложений в верхней части колонки Application Insights.
Просмотреть данные можно также на портале Azure. Выберите панель мониторинга слева, а затем выберите нужную панель мониторинга в раскрывающемся списке.
Здесь вы увидите некоторые стандартные сведения о производительности бота и дополнительные запросы, которые вы закрепили на панели мониторинга.