Adicionar telemetria ao seu bot

APLICA-SE A: SDK v4

O log de telemetria permite que os aplicativos de bot enviem dados de eventos para serviços de telemetria, como o Application Insights. A telemetria oferece insights sobre seu bot, mostrando quais recursos são mais usados, detecta comportamentos indesejados e oferece visibilidade da disponibilidade, desempenho e uso.

Este artigo descreve como implementar a telemetria em seu bot usando o Application Insights. Este artigo cobre:

• O código necessário para conectar a telemetria em seu bot e se conectar ao Application Insights.
• Como habilitar a telemetria nas caixas de diálogo do bot.
• Como habilitar a telemetria para capturar dados de uso de outros serviços, como os serviços de IA do Azure.
• Como visualizar seus dados de telemetria no Application Insights.

Importante

Para um bot regional que pode coletar informações de identificação pessoal (PII) na telemetria, o recurso do Application Insights e o recurso do Bot do Azure devem estar na mesma região que o bot. Se os recursos estiverem em regiões diferentes, as PII poderão deixar a região geográfica do bot.

Pré-requisitos

C#

• O código de exemplo do CoreBot
• O código de exemplo do Application Insights
• Uma assinatura do Microsoft Azure
• Uma chave do Application Insights
• Familiaridade com o Application Insights
• git

Observação

O código de exemplo do Application Insights foi criado com base no código de exemplo do CoreBot. Este artigo guiará você pela modificação do código de exemplo do CoreBot para incorporar a telemetria. Se você estiver acompanhando no Visual Studio, terá o código de exemplo do Application Insights quando terminar.

JavaScript

• O código de exemplo do CoreBot
• O código de exemplo do Application Insights
• Uma assinatura do Microsoft Azure
• Uma chave do Application Insights
• Familiaridade com o Application Insights
• Visual Studio Code
• Node.js versão 10.14 ou posterior. Use o comando node --version para determinar a versão do nó que você tem.
• Bot Framework Emulator

Observação

O código de exemplo do Application Insights foi criado com base no código de exemplo do CoreBot. Este artigo guiará você pela modificação do código de exemplo do CoreBot para incorporar a telemetria. Se você estiver acompanhando no Visual Studio Code, terá o código de exemplo do Application Insights quando terminar.

Habilitar a telemetria no bot

C#

Este artigo começa com o aplicativo de exemplo CoreBot e adiciona o código necessário para integrar a telemetria a qualquer bot. Isso permitirá que o Application Insights comece a acompanhar as solicitações.

Importante

Se você não configurou sua conta do Application Insights e criou sua chave do Application Insights, faça isso antes de continuar.

1. Abra o aplicativo de exemplo CoreBot 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;
   using Microsoft.Bot.Builder.Integration.AspNet.Core;
   

   Dica

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

4. Inclua o código a seguir no método ConfigureServices() em Startup.cs. Isso tornará 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();
   
           // 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>();
       ...
   }
   

   Dica

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

5. Instrua o adaptador a usar o código de middleware que foi adicionado ao método ConfigureServices(). Você faz isso com AdapterWithErrorHandler.cs o parâmetro TelemetryInitializerMiddleware telemetryInitializerMiddleware na lista de parâmetros do construtor e a Use(telemetryInitializerMiddleware); instrução no construtor, conforme mostrado aqui:

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

6. Você também precisará adicionar Microsoft.Bot.Builder.Integration.ApplicationInsights.Core à sua lista de instruções de uso em AdapterWithErrorHandler.cs.

7. 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. Por exemplo, a conexão e os metadados dos serviços do Cosmos DB, do Application Insights e do Azure AI são armazenados lá. A adição ao arquivo appsettings.json deve estar neste formato:

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

   Observação

   Detalhes sobre como obter a chave de instrumentação do Application Insights podem ser encontrados no artigo Chaves do Application Insights.

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

Habilitar a telemetria nas caixas de diálogo do bot

Ao adicionar uma nova caixa de diálogo a qualquer ComponentDialog, ela herdará o Microsoft.Bot.Builder.IBotTelemetryClient da caixa de diálogo pai. Por exemplo, no aplicativo de exemplo CoreBot, todas as caixas de diálogo são adicionadas ao MainDialog, que é um ComponentDialog. Depois de definir a propriedade TelemetryClient como MainDialog, todas as caixas de diálogo adicionadas a ela herdarão automaticamente o telemetryClient dela, portanto, ele não precisa ser definido explicitamente ao adicionar caixas de diálogo.

Siga as etapas abaixo para atualizar o exemplo de CoreBot:

1. Em MainDialog.cs, atualize a lista de parâmetros do construtor para incluir o parâmetro IBotTelemetryClient e, em seguida, defina a propriedade TelemetryClient da MainDialog para esse valor, conforme mostrado no seguinte snippet de código:

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

Dica

Se você estiver acompanhando e atualizando o código de exemplo do CoreBot, poderá consultar o código de exemplo do Application Insights se tiver algum problema.

A telemetria agora é adicionada às caixas de diálogo do bot. Se você executar seu bot agora, deverá ver as coisas sendo registradas no Application Insights; no entanto, se você tiver alguma tecnologia integrada, como um serviço de IA do Azure, também precisará adicioná-la TelemetryClient a esse código.

JavaScript

Este artigo começa com o aplicativo de exemplo CoreBot e adiciona o código necessário para integrar a telemetria a qualquer bot. Isso permitirá que o Application Insights comece a acompanhar as solicitações.

Importante

Se você não configurou sua conta do Application Insights e criou sua chave do Application Insights, faça isso antes de continuar.

1. Abra o aplicativo de exemplo CoreBot no Visual Studio Code.

2. Adicione a chave do Application Insights ao arquivo.env: InstrumentationKey=<EnterInstrumentationKeyHere>. O .env arquivo contém metadados sobre serviços externos que o bot usa durante a execução. Por exemplo, a conexão e os metadados dos serviços de IA do Application Insights e do Azure são armazenados lá. A adição ao arquivo .env deve estar neste formato:

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

   Observação

   Detalhes sobre como obter a chave de instrumentação do Application Insights podem ser encontrados no artigo Chaves do Application Insights.

3. Adicione uma referência aos módulos ApplicationInsightsTelemetryClient e TelemetryInitializerMiddleware que estão localizados no botbuilder-applicationinsights SDK do Bot Framework. Para fazer isso, adicione o seguinte código começando próximo ao topo de index.js, logo após o código para importar os pacotes necessários:

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

   Dica

   Os exemplos de bot JavaScript usam Node.js, que segue o sistema de módulos CommonJS, e a função integrada require para incluir módulos que existem em arquivos separados.

4. Crie uma nova função no final de named getTelemetryClient que usa sua chave de index.js instrumentação como um parâmetro e retorna um cliente de telemetria usando o módulo referenciado ApplicationInsightsTelemetryClient anteriormente. Esse cliente de telemetria é para onde seus dados de telemetria serão enviados, nesse caso, o 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. Em seguida, você precisa adicionar o middleware de telemetria ao pipeline de middleware do adaptador. Para fazer isso, adicione o seguinte código, começando logo após o código de tratamento de erros:

   
   // 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. Para que sua caixa de diálogo relate dados de telemetria, ela telemetryClient deve corresponder à usada para o middleware de telemetria, ou seja, 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. Depois de criar o objeto de servidor Web HTTP restify, instrua-o a usar o bodyParser manipulador.

       }
       return new NullTelemetryClient();
   }
   

   Dica

   Isso usa a função restifybodyParser. restify é uma estrutura de serviço da Web "Node.js otimizada para criar serviços da Web RESTful semanticamente corretos, prontos para uso em produção em escala. O restify otimiza a introspecção e o desempenho e é usado em algumas das maiores implantações de Node.js da Terra." Para obter mais informações, consulte o site restify.

   Node.js segue o sistema de módulos CommonJS e usa a função integrada require para incluir módulos que existem em arquivos separados.

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

Ativar ou desativar o registro de eventos de atividade e informações pessoais

C#

Habilitar ou desabilitar o log de atividades

Por padrão, o TelemetryInitializerMiddleware usará o TelemetryLoggerMiddleware para registrar a telemetria em log quando o bot enviar/receber atividades. O log de atividades cria logs de eventos personalizados em seu recurso do Application Insights. Se desejar, você pode desativar o TelemetryInitializerMiddleware log de eventos de atividade definindo logActivityTelemetry como false no ao registrá-lo no 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);
            });
    ...
}

Ativar ou desativar o registro de informações pessoais

Por padrão, se o log de atividades estiver habilitado, algumas propriedades nas atividades de entrada/saída serão excluídas do log, pois provavelmente conterão informações pessoais, como nome de usuário e o texto da atividade. Você pode optar por incluir essas propriedades em seu log fazendo a alteração a seguir a Startup.cs ao registrar o 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);
            });
    ...
}

Em seguida, veremos o que precisa ser incluído para adicionar funcionalidade de telemetria às caixas de diálogo. Isso permitirá que você obtenha informações adicionais, tais como quais caixas de diálogo serão executadas, além de estatísticas sobre cada uma delas.

JavaScript

Habilitar ou desabilitar o log de atividades

Por padrão, o TelemetryInitializerMiddleware usará a telemetria para registrar quando o TelemetryLoggerMiddleware bot enviar ou receber atividades. O log de atividades cria logs de eventos personalizados em seu recurso do Application Insights. Se desejar, você pode desativar o TelemetryInitializerMiddleware registro de eventos de atividade definindo logActivityTelemetry como false no ao registrá-lo no index.js.

O snippet de código a seguir vem de sample 21.corebot-app-insightse mostra a chamada para 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();

O trecho de código abaixo mostra a alteração necessária no exemplo 21.corebot-app-insights, na chamada para TelemetryInitializerMiddleware para desabilitar o log de atividades:

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

Ativar ou desativar o registro de informações pessoais

Quando o log de atividades está habilitado, algumas propriedades nas atividades de entrada/saída são excluídas do log por padrão, pois provavelmente contêm informações pessoais, como nome de usuário e o texto da atividade. Você pode optar por incluir essas propriedades em seu registro alterando o logPersonalInformation parâmetro de false para true ao registrar o TelemetryLoggerMiddleware no 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();

Em seguida, veremos o que precisa ser incluído para adicionar funcionalidade de telemetria às caixas de diálogo. Isso permitirá que você obtenha informações adicionais, tais como quais caixas de diálogo serão executadas, além de estatísticas sobre cada uma delas.

Habilitar a telemetria para capturar dados de uso de outros serviços, tais como o LUIS e o QnA Maker

Observação

O QnA Maker da IA do Azure será desativada em 31 de março de 2025. A partir de 1° de outubro de 2022, não será mais possível criar recursos ou bases 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 de 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, confira reconhecimento de linguagem natural.

Observação

O reconhecimento de linguagem (LUIS) será desativado em 1º de outubro de 2025. A partir de 1º de abril de 2023, você não poderá criar recursos do LUIS. Uma versão mais recente do reconhecimento de linguagem já está disponível como parte da Linguagem de IA do Azure.

A compreensão da linguagem coloquial (CLU), um recurso da Linguagem de IA do Azure, é a versão atualizada do LUIS. Para obter mais informações sobre o suporte ao reconhecimento de linguagem no SDK do Bot Framework, confira Reconhecimento de linguagem natural.

C#

Em seguida, implementaremos a funcionalidade de telemetria em seu serviço LUIS. O serviço LUIS tem log de telemetria interno disponível, portanto, há pouco que você precise fazer para começar a obter dados de telemetria do LUIS. Se você estiver interessado em habilitar a telemetria em um bot habilitado para QnA Maker, consulte Adicionar telemetria ao bot do QnA Maker

1. O parâmetro IBotTelemetryClient telemetryClient é necessário no construtor FlightBookingRecognizer em FlightBookingRecognizer.cs:

   public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
   

2. Em seguida, habilite o telemetryClient quando você criar seu LuisRecognizer no FlightBookingRecognizer construtor. Faça isso adicionando o telemetryClient como um novo 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);
   }
   

Isso é tudo, agora você deve ter um bot funcional que registra dados de telemetria no Application Insights. Você pode usar o Bot Framework Emulator para executar o bot localmente. Você não deve experienciar nenhuma alteração no comportamento do bot, mas ele estará registrando informações no Application Insights. Interaja com o bot enviando várias mensagens e, na próxima seção, examinaremos os resultados da telemetria no Application Insights.

Para obter informações sobre como testar e depurar o bot, consulte os seguintes artigos:

• Depurar um bot
• Diretrizes para testes e depuração
• Depurar com o emulador

JavaScript

Em seguida, implementaremos a funcionalidade de telemetria em seu serviço LUIS. O serviço LUIS tem log de telemetria interno disponível, portanto, há pouco que você precise fazer para começar a obter dados de telemetria do LUIS.

Para habilitar o cliente de telemetria no reconhecedor do LUIS:

1. Abrir FlightBookingRecognizer.js

2. Passe o telemetryClient parâmetro para o FlightBookingRecognizer construtor:

   constructor(config, telemetryClient) {
   

3. Defina o telemetryClient recognizerOptions campo do objeto para a telemetryClient propriedade que é passada para o FlightBookingRecognizer construtor, uma vez feito isso, seu construtor aparecerá da seguinte forma:

   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. E, finalmente, você precisa incluir o telemetryClient ao criar uma instância do FlightBookingRecognizer in index.js:

   const memoryStorage = new MemoryStorage();
   

É isso; você deve ter um bot funcional que registre dados de telemetria no Application Insights. Você pode usar o Bot Framework Emulator para executar o bot localmente. Você não deve experienciar nenhuma alteração no comportamento do bot, mas ele estará registrando informações no Application Insights. Interaja com o bot enviando várias mensagens e a próxima seção descreve como examinar os resultados de telemetria no Application Insights.

Para obter informações sobre como testar e depurar o bot, consulte os seguintes artigos:

• Depurar um bot
• Diretrizes para testes e depuração
• Depurar com o emulador

Visualizar os dados telemétricos no Application Insights

O Application Insights monitora a disponibilidade, o desempenho e o uso do aplicativo de bot, esteja ele hospedado na nuvem ou localmente. Ele usa a poderosa plataforma de análise de dados no Azure Monitor para fornecer insights profundos sobre as operações do aplicativo e diagnosticar erros sem esperar que um usuário os relate. Há algumas maneiras de ver os dados de telemetria coletados pelo Application Insights, duas das principais maneiras são por meio de consultas e do painel.

Consultar os dados telemétricos no Application Insights usando o Kusto Queries

Use esta seção como um ponto de partida para aprender a usar consultas de log no Application Insights. Ela demonstra duas consultas úteis e fornece links para outras documentações com informações adicionais.

Para consultar seus dados

1. Vá para o Portal do Azure

2. Para acessar a página do Application Insights, selecione Monitorar, Aplicativos e localize-o lá.

3. Uma vez no Application Insights, selecione Logs (Análise).

   

4. Isso abrirá a janela Consulta. Insira a consulta a seguir e selecione Executar:

   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. Isso retornará o percentual de caixas de diálogo em cascata que são executados até a conclusão.

   

Dica

Você pode fixar qualquer consulta ao seu painel do Application Insights selecionando o botão no canto superior direito da folha Logs (Análise). Basta selecionar o painel ao qual você deseja que ele seja fixado e ele estará disponível na próxima vez que você visitar esse painel.

O painel do Application Insights

Sempre que você criar um recurso do Application Insights no Azure, um painel será automaticamente criado e associado a ele. Você pode ver esse painel selecionando o botão na parte superior da sua folha do Application Insights, rotulado Painel de Aplicativo.

Como alternativa, para exibir os dados, acesse o portal do Azure. Selecione Painel à esquerda e, em seguida, selecione o painel desejado na lista suspensa.

Lá, você verá algumas informações padrão sobre o desempenho do bot e quaisquer consultas adicionais que tenha fixado ao seu painel.

Informações Adicionais

• Adicionar telemetria ao bot do QnA Maker
• O que é o Application Insights?
• Usar a Pesquisa no Application Insights
• Criar painéis de KPI personalizados usando o Azure Application Insights