Adicionar telemetria ao bot do QnA Maker

  • Artigo

APLICA-SE A: SDK v4

Observação

O QnA Maker de IA do Azure será desativado em 31 de março de 2025. A partir de 1º de outubro de 2022, você não poderá criar novos recursos ou bases de dados de conhecimento do QnA Maker. Uma versão mais recente da funcionalidade de perguntas e respostas agora está disponível como parte da Linguagem de IA do Azure.

Respostas às perguntas personalizadas, um recurso da Linguagem de IA do Azure, é a versão atualizada do serviço QnA Maker. Para obter mais informações sobre o suporte a perguntas e respostas no SDK do Bot Framework, consulte Compreensão da linguagem natural.

O log de telemetria permite que aplicativos bot enviem dados de evento para serviços de telemetria, como o Application Insights. A telemetria oferece informações sobre o bot mostrando quais recursos são mais usados, detecta comportamento indesejado e fornece visibilidade da disponibilidade, do desempenho e do uso.

As TelemetryLoggerMiddleware classes e QnAMaker no SDK do Bot Framework habilitam o log de telemetria em bots habilitados para QnA Maker. TelemetryLoggerMiddleware é um componente de middleware que registra a telemetria sempre que as mensagens são recebidas, enviadas, atualizadas ou excluídas, e a QnAMaker classe fornece registro em log personalizado que estende os recursos de telemetria.

Neste artigo, você aprenderá sobre:

  • O código necessário para ligar a telemetria a seu bot.
  • O código necessário para habilitar o log do QnA Maker pronto para uso e relatórios que usam as propriedades de evento padrão.
  • Como modificar ou estender as propriedades de evento padrão do SDK para habilitar uma ampla gama de necessidades de relatório.

Pré-requisitos

Observação

Este artigo baseia-se no código de exemplo do QnA Maker percorrendo as etapas necessárias para incorporar a telemetria.

Adicionar código de telemetria ao bot do QnA Maker

Começaremos com o aplicativo de exemplo QnA Maker e adicionaremos o código necessário para integrar a telemetria a um bot que usa o serviço QnA Maker. Isso permitirá que o Application Insights acompanhe as solicitações.

  1. Abra o aplicativo de exemplo QnA Maker no Visual Studio.

  2. Adicione o pacote NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Para obter mais informações sobre como usar o NuGet, confira Instalar e gerenciar pacotes no Visual Studio:

  3. Inclua as instruções a seguir em Startup.cs:

    using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Bot.Builder.ApplicationInsights;
using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;

    Observação

    Se você estiver acompanhando atualizando o código de exemplo do QnA Maker, observará que a instrução using para Microsoft.Bot.Builder.Integration.AspNet.Core já existe no exemplo do QnA Maker.

  4. Adicione o código a seguir ao método ConfigureServices() em Startup.cs. Isso torna os serviços de telemetria disponíveis para o bot por meio da DI (injeção de dependência):

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

    // Add the standard telemetry client
    services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>();

    // Create the telemetry middleware to track conversation events
    services.AddSingleton<TelemetryLoggerMiddleware>();

    // Add the telemetry initializer middleware
    services.AddSingleton<IMiddleware, TelemetryInitializerMiddleware>();

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

    Observação

    Se você estiver acompanhando atualizando o código de exemplo do QnA Maker, observará que já services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); existe.

  5. Instrua o adaptador a usar o código de middleware que foi adicionado ao método ConfigureServices(). Abra AdapterWithErrorHandler.cs e adicione IMiddleware middleware à lista de parâmetros de construtores. Adicione a instrução Use(middleware); como a última linha no construtor:

    public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
        : base(credentialProvider)
{
    ...

    Use(middleware);
}

  6. Adicione a chave de instrumentação do Application Insights ao seu arquivo appsettings.json. O appsettings.json arquivo contém metadados sobre serviços externos que o bot usa durante a execução, como conexão e metadados para Cosmos DB, Application Insights e QnA Maker. A adição ao arquivo appsettings.json deve estar neste formato:

    {
    "MicrosoftAppId": "",
    "MicrosoftAppPassword": "",
    "QnAKnowledgebaseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "QnAEndpointKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "QnAEndpointHostName": "https://xxxxxxxx.azurewebsites.net/qnamaker",
    "ApplicationInsights": {
        "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}

    Observação

Neste ponto, o trabalho preliminar para habilitar a telemetria usando o Application Insights é feito. Você pode executar o bot localmente usando o Bot Framework Emulator e, em seguida, entrar no Application Insights para ver o que está sendo registrado, como tempo de resposta, integridade geral do aplicativo e informações gerais de execução.

Dica

Para obter informações sobre informações pessoais, consulte Habilitar ou desabilitar o registro em log de informações pessoais e eventos de atividade.

Em seguida, veremos o que precisa ser incluído para adicionar a funcionalidade de telemetria ao serviço QnA Maker.

Habilitar a telemetria para capturar dados de uso do serviço QnA Maker

O serviço QnA Maker tem o log de telemetria interno disponível, portanto, há pouco que você precisa fazer para começar a obter dados de telemetria do QnA Maker. Primeiro, veremos como incorporar a telemetria ao código QnA Maker para habilitar o log de telemetria interno e, em seguida, aprenderemos a substituir ou adicionar propriedades aos dados de evento existentes para atender a uma ampla variedade de necessidades de relatório.

Habilitar o log padrão do QnA Maker

  1. Crie um campo privado somente leitura do tipo IBotTelemetryClient em sua classe QnABot em QnABot.cs:

    public class QnABot : ActivityHandler
    {
        private readonly IBotTelemetryClient _telemetryClient;
        ...
}

  2. Adicione um parâmetro IBotTelemetryClient ao construtor da classe QnABot no QnABot.cs e atribua o valor dele ao campo privado criado na etapa anterior:

    public QnABot(IConfiguration configuration, ILogger<QnABot> logger, IHttpClientFactory httpClientFactory, IBotTelemetryClient telemetryClient)
{
    ...
    _telemetryClient = telemetryClient;
}

  3. O parâmetro telemetryClient é necessário ao instanciar o novo objeto QnAMaker em QnABot.cs:

    var qnaMaker = new QnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);

    Dica

    Verifique se os nomes de propriedade usados nas _configuration entradas correspondem aos nomes de propriedade usados no arquivo AppSettings.json e se os valores dessas propriedades são obtidos selecionando o botão Exibir Código na página Minhas bases de dados de conhecimento no portal do QnA Maker:

    Ilustração de onde as configurações do aplicativo são encontradas no portal do LUIS.

Exibir dados de telemetria registrados nas entradas padrão do QnA Maker

Você pode exibir os resultados do uso do bot do QnA Maker no Application Insights depois de executar o bot no Bot Framework Emulator executando as seguintes etapas:

  1. No portal do Azure, vá para o recurso application insights do bot.

  2. Em Monitoramento, selecione Logs.

  3. Insira a consulta Kusto a seguir e selecione Executar.

    customEvents
| where name == 'QnaMessage'
| extend answer = tostring(customDimensions.answer)
| summarize count() by answer

  4. Deixe esta página aberta no navegador; voltaremos a ele depois de adicionar uma nova propriedade personalizada.

Dica

Se você não estiver familiarizado com a linguagem de consulta Kusto usada para gravar consultas de log no Azure Monitor, mas estiver familiarizado com a linguagem de consulta SQL, talvez a folha de consulta de log do SQL to Azure Monitor seja útil.

Modificar ou estender propriedades de evento padrão

Se você precisar de propriedades que não estão definidas na QnAMaker classe, há duas maneiras de lidar com isso, ambas exigem a criação de sua própria classe derivada da QnAMaker classe . A primeira é explicada na seção abaixo, intitulada Adicionar propriedades, em que você adiciona propriedades ao evento QnAMessage existente. O segundo método permite que você crie eventos aos quais é possível adicionar propriedades, conforme descrito em Adicionar novos eventos com propriedades personalizadas.

Observação

O evento QnAMessage faz parte do SDK do Bot Framework e fornece todas as propriedades de evento prontas para uso que são registradas em log no Application Insights.

Adicionar propriedades

A seguir, é demonstrado como é possível derivar da classe QnAMaker. O exemplo mostra a adição da propriedade "MyImportantProperty" ao evento QnAMessage. O evento QnAMessage é registrado sempre que uma chamada a GetAnswers do QnA é realizada.

Depois de aprender a adicionar propriedades personalizadas, aprenderemos a criar um novo evento personalizado e associar propriedades a ele, então executaremos o bot localmente usando o Bot Framework Emulator e veremos o que está sendo registrado no Application Insights usando a linguagem de consulta Kusto.

  1. Crie uma classe chamada MyQnAMaker no namespace Microsoft.BotBuilderSamples que herda da classe QnAMaker e salve-a como MyQnAMaker.cs. Para herdar da QnAMaker classe , você precisará adicionar a Microsoft.Bot.Builder.AI.QnA instrução using. O código deve aparecer da seguinte maneira:

    using Microsoft.Bot.Builder.AI.QnA;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {

    }
}

  2. Adicione um construtor de classe a MyQnAMaker. Você precisará de mais duas instruções using para os parâmetros do construtor para System.Net.Http e Microsoft.Bot.Builder:

    using Microsoft.Bot.Builder.AI.QnA;
using System.Net.Http;
using Microsoft.Bot.Builder;

namespace Microsoft.BotBuilderSamples
{
    public class MyQnAMaker : QnAMaker
    {
        public MyQnAMaker(
            QnAMakerEndpoint endpoint,
            QnAMakerOptions options = null,
            HttpClient httpClient = null,
            IBotTelemetryClient telemetryClient = null,
            bool logPersonalInformation = false)
            : base(endpoint, options, httpClient, telemetryClient, logPersonalInformation)
        {

        }
    }
}

  3. Adicione a nova propriedade ao evento QnAMessage após o construtor e inclua as instruções System.Collections.Generic, System.Threading e System.Threading.Tasks:

    using Microsoft.Bot.Builder.AI.QnA;
using System.Net.Http;
using Microsoft.Bot.Builder;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace Microsoft.BotBuilderSamples
{
        public class MyQnAMaker : QnAMaker
        {
        ...

        protected override async Task OnQnaResultsAsync(
                            QueryResult[] queryResults,
                            Microsoft.Bot.Builder.ITurnContext turnContext,
                            Dictionary<string, string> telemetryProperties = null,
                            Dictionary<string, double> telemetryMetrics = null,
                            CancellationToken cancellationToken = default(CancellationToken))
        {
            var eventData = await FillQnAEventAsync(
                                    queryResults,
                                    turnContext,
                                    telemetryProperties,
                                    telemetryMetrics,
                                    cancellationToken)
                                .ConfigureAwait(false);

            // Add new property
            eventData.Properties.Add("MyImportantProperty", "myImportantValue");

            // Log QnAMessage event
            TelemetryClient.TrackEvent(
                            QnATelemetryConstants.QnaMsgEvent,
                            eventData.Properties,
                            eventData.Metrics
                            );
        }

    }
}

  4. Modifique o bot para usar a nova classe, em vez de criar um QnAMaker objeto MyQnAMaker em QnABot.cs:

    var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
            {
                KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                EndpointKey = _configuration["QnAEndpointKey"],
                Host = _configuration["QnAEndpointHostName"]
            },
            null,
            httpClient,
            _telemetryClient);
Exibir dados de telemetria registrados na nova propriedade MyImportantProperty

Depois de executar o bot no Emulador, você pode exibir os resultados no Application Insights fazendo o seguinte:

  1. Volte para o navegador que tem a exibição Logs (Análise) ativa.

  2. Insira a consulta em Kusto a seguir e selecione Executar. Isso fornecerá uma contagem do número de vezes que a nova propriedade foi executada:

    customEvents
| where name == 'QnaMessage'
| extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
| summarize count() by MyImportantProperty

  3. Para mostrar detalhes em vez da contagem, remova a última linha e execute novamente a consulta:

    customEvents
| where name == 'QnaMessage'
| extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)

Adicionar novos eventos com propriedades personalizadas

Se precisar registrar dados em log para um evento diferente de QnaMessage, você poderá criar seu próprio evento personalizado com suas próprias propriedades. Para fazer isso, adicionaremos código ao final da classe da MyQnAMaker seguinte maneira:

public class MyQnAMaker : QnAMaker
{
    ...

    // Create second event.
    var secondEventProperties = new Dictionary<string, string>();

    // Create new property for the second event.
    secondEventProperties.Add(
                        "MyImportantProperty2",
                        "myImportantValue2");

    // Log secondEventProperties event
    TelemetryClient.TrackEvent(
                    "MySecondEvent",
                    secondEventProperties);

}

O painel do Application Insights

Sempre que você cria um recurso do Application Insights no Azure, o Azure cria uma nova dashboard associada ao recurso. Para exibir o dashboard na folha Application Insights, selecione Painel do Aplicativo.

Como alternativa, para exibir os dados, vá para a portal do Azure, expanda o menu do portal e selecione Painel. Em seguida, selecione a dashboard desejada no menu suspenso.

O dashboard exibe algumas informações padrão sobre o desempenho do bot e outras consultas que você fixou ao dashboard.

Informações adicionais