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

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

  • Статья

ПРИМЕНИМО К: Пакет 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. Формат добавляемого в файл 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 все диалоговые окна, добавленные в него, будут автоматически наследовать от него 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), функция языка ИИ Azure, — это обновленная версия 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) на странице Application Insights бота.

  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, нажав кнопку в правом верхнем углу колонки Журналы (Аналитика). Просто выберите нужную панель мониторинга, и вы сможете выбрать этот запрос при ее следующем открытии.

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

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

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

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

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

Дополнительные сведения