Adicionar telemetria ao seu bot

APLICA-SE A: SDK v4

O log de telemetria permite que aplicativos de bot enviem dados de evento para serviços de telemetria, como o Application Insights. A telemetria oferece insights sobre seu bot mostrando quais recursos são mais usados, detecta comportamento indesejado e oferece visibilidade sobre 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 no bot e conectar-se 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 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 com o bot. Se os recursos estiverem em regiões diferentes, a PII poderá 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 até 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.
• Emulador do bot Framework

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 em Visual Studio Code, terá o código de exemplo do Application Insights até terminar.

Habilitar a telemetria no bot

C#

Este artigo começa no 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ê ainda 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 para Microsoft.Bot.Builder.Integration.AspNet.Core já existe no exemplo 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, 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(). Faça 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 using no 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 de IA do Cosmos DB, do Application Insights e do Azure 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 é feito. Você pode executar o bot localmente usando o Emulador 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.

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 a telemetryClient dela, portanto, ela não precisará ser definida 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 estiver acompanhando e atualizando o código de exemplo do CoreBot, você poderá consultar o código de exemplo do Application Insights se tiver problemas.

A telemetria agora é adicionada às caixas de diálogo do bot. Se você executar o bot agora, verá 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á adicionar o 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ê ainda 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 em 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 perto da parte superior do 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 interna require para incluir módulos que existem em arquivos separados.

4. Crie uma nova função no final do chamado getTelemetryClient que usa sua chave de index.js instrumentação como um parâmetro e retorna um cliente de telemetria usando o ApplicationInsightsTelemetryClient módulo referenciado anteriormente. Esse cliente de telemetria é para o qual os 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 erro:

   
   // 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 restify do servidor Web HTTP, instrua-o a usar o bodyParser manipulador.

       }
       return new NullTelemetryClient();
   }
   

   Dica

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

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

Neste ponto, o trabalho preliminar para habilitar a telemetria usando o Application Insights é feito. Você pode executar o bot localmente usando o Emulador 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.

Habilitar ou desabilitar o registro em log de informações pessoais e eventos de atividade

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ê poderá desabilitar o log de eventos de atividade definindo logActivityTelemetry como false no TelemetryInitializerMiddleware ao registrá-lo em 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);
            });
    ...
}

Habilitar ou desabilitar o registro em log 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 registro em log, pois provavelmente conterão informações pessoais, como o 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 a 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á o TelemetryLoggerMiddleware para registrar a telemetria quando o bot enviar ou receber atividades. O log de atividades cria logs de eventos personalizados em seu recurso do Application Insights. Se desejar, você poderá desabilitar o log de eventos de atividade definindo logActivityTelemetry como false no TelemetryInitializerMiddleware ao registrá-lo no index.js.

O snippet de código a seguir vem do exemplo 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 snippet de código abaixo mostra a alteração necessária no exemplo 21.corebot-app-insights, na chamada para TelemetryInitializerMiddleware 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);

Habilitar ou desabilitar o registro em log de informações pessoais

Quando o log de atividades está habilitado, algumas propriedades nas atividades de entrada/saída são excluídas do registro em log por padrão, pois elas provavelmente contêm informações pessoais, como o nome de usuário e o texto da atividade. Você pode optar por incluir essas propriedades em seu log 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 a 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 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.

Observação

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

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

C#

Em seguida, implementaremos a funcionalidade de telemetria em seu serviço LUIS. O serviço LUIS tem o log de telemetria interno disponível, portanto, há pouco que você precisa 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 o FlightBookingRecognizerLuisRecognizer no 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 o log de telemetria interno disponível, portanto, há pouco que você precisa fazer para começar a obter dados de telemetria do LUIS.

Para habilitar o cliente de telemetria no reconhecedor do LUIS:

1. Abra FlightBookingRecognizer.js

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

   constructor(config, telemetryClient) {
   

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

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

   const memoryStorage = new MemoryStorage();
   

É isso, é isso. 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 a próxima seção descreve como examinar 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

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 sua 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 no dashboard 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 dashboard 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