Поделиться через


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

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

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

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

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

Внимание

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

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

Примечание.

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

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

Эта статья начинается с примера приложения 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 содержит метаданные о внешних службах, которые бот использует во время выполнения. Например, подключение и метаданные 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, выполните следующие шаги:

  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 в этот код.

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

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

По умолчанию 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"

  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.

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

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

    Пример выходных данных запроса App Insights.

Совет

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

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

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

Снимок экрана: кнопка

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

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

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