Add telemetry to your bot (Adicionar telemetria ao bot)

APLICA-SE A: SDK v4

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

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

• O código necessário para conectar a telemetria em seu bot e conectar-se ao Application Insights.
• Como ativar 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) em telemetria, seu recurso do Application Insights e seu recurso de Bot do Azure devem estar na mesma região que o bot. Se os recursos estiverem em regiões diferentes, a PII pode 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

Nota

O código de exemplo do Application Insights foi criado sobre o código de exemplo do CoreBot. Este artigo irá orientá-lo através da modificação do código de exemplo do CoreBot para incorporar 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.
• Emulador de Bot Framework

Nota

O código de exemplo do Application Insights foi criado sobre o código de exemplo do CoreBot. Este artigo irá orientá-lo através da modificação do código de exemplo do CoreBot para incorporar telemetria. Se você estiver acompanhando no Visual Studio Code, terá o código de exemplo do Application Insights quando terminar.

Habilite a telemetria em seu bot

C#

Este artigo começa a partir do aplicativo de exemplo CoreBot e adiciona o código necessário para integrar a telemetria em qualquer bot. Isso permitirá que o Application Insights comece a rastrear 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 Microsoft.Bot.Builder.Integration.ApplicationInsights.Core pacote NuGet. Para obter mais informações sobre como usar o NuGet, consulte Instalar e gerenciar pacotes no Visual Studio:

3. Inclua as seguintes instruções 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;
   

   Gorjeta

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

4. Inclua o seguinte código no ConfigureServices() método em Startup.cs. Isso tornará os serviços de telemetria disponíveis para seu bot por meio de injeção de dependência (DI):

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

   Gorjeta

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

5. Instrua o adaptador a usar o código de middleware que foi adicionado ao ConfigureServices() método. 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 como 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 em seu appsettings.json arquivo. 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, Application Insights e Azure AI são armazenados lá. A adição ao seu appsettings.json arquivo deve estar neste formato:

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

   Nota

   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 está concluído. Você pode executar seu 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.

Habilite 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 de sua 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 para MainDialog, todas as caixas de diálogo adicionadas a ela herdarão automaticamente o telemetryClient dele, portanto, ele não precisa ser explicitamente definido ao adicionar caixas de diálogo.

Siga as etapas abaixo para atualizar seu exemplo de CoreBot:

1. No MainDialog.cs, atualize a lista de parâmetros do construtor para incluir o IBotTelemetryClient parâmetro e, em seguida, defina a propriedade TelemetryClient do MainDialog's para esse valor, conforme mostrado no seguinte trecho 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;
       ...
   }
   

Gorjeta

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, verá coisas sendo registradas no Application Insights; no entanto, se você tiver qualquer tecnologia integrada, como um serviço de IA do Azure, precisará adicionar o TelemetryClient a esse código também.

JavaScript

Este artigo começa com o aplicativo de exemplo CoreBot e adiciona o código necessário para integrar a telemetria em qualquer bot. Isso permitirá que o Application Insights comece a rastrear 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 seu .env arquivo: 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 do Application Insights e da IA do Azure são armazenados lá. A adição ao seu .env arquivo deve estar neste formato:

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

   Nota

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

   Gorjeta

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

4. Crie uma nova função no final do nome getTelemetryClient que tome sua chave de instrumentação como um parâmetro e retorne um cliente de index.js telemetria usando o ApplicationInsightsTelemetryClient módulo que você mencionou anteriormente. Este cliente de telemetria é para onde seus dados de telemetria serão enviados, neste 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 do servidor Web HTTP restify, instrua-o a usar o bodyParser manipulador.

       }
       return new NullTelemetryClient();
   }
   

   Gorjeta

   Isso usa a função restifybodyParser. restify é uma estrutura de serviço Web "A Node.js otimizada para criar serviços Web RESTful semanticamente corretos prontos para uso em produção em escala. restify otimiza para introspeçã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 está concluído. Você pode executar seu 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.

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

C#

Ativar ou desativar o registo de atividades

Por padrão, o TelemetryInitializerMiddleware usará o para registrar a telemetria TelemetryLoggerMiddleware quando seu 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 registro 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 registo de informações pessoais

Por padrão, se o registro de atividades estiver habilitado, algumas propriedades nas atividades de entrada/saída serão excluídas do registro, 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 registro fazendo a seguinte alteração para 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, como quais caixas de diálogo são executadas e estatísticas sobre cada uma delas.

JavaScript

Ativar ou desativar o registo de atividades

Por padrão, o TelemetryInitializerMiddleware usará o para registrar a telemetria TelemetryLoggerMiddleware 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ê pode desativar o TelemetryInitializerMiddleware registro de eventos de atividade definindo logActivityTelemetry como false no ao registrá-lo no index.js.

O trecho 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 trecho de código abaixo mostra a alteração necessária no exemplo 21.corebot-app-insights, na chamada para TelemetryInitializerMiddleware desativar o registro 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 registo de informações pessoais

Quando o registo de atividades está ativado, algumas propriedades das atividades de entrada/saída são excluídas do registo por predefinição, uma vez que é provável que contenham informações pessoais, tais como o nome de utilizador e o texto da atividade. Você pode optar por incluir essas propriedades em seu registro alterando o logPersonalInformation parâmetro de false para ao true registrar o TelemetryLoggerMiddleware in 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, como quais caixas de diálogo são executadas e estatísticas sobre cada uma delas.

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

Nota

O Azure AI QnA Maker 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 conhecimento do QnA Maker. Uma versão mais recente do recurso de perguntas e respostas agora está disponível como parte da Linguagem de IA do Azure.

A resposta a 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 de linguagem natural.

Nota

O Language Understanding (LUIS) será aposentado em 1 de outubro de 2025. A partir de 1 de abril de 2023, não será possível criar novos recursos LUIS. Uma versão mais recente do entendimento de idiomas agora está disponível como parte do Azure AI Language.

O entendimento de linguagem conversacional (CLU), um recurso do Azure AI Language, é a versão atualizada do LUIS. Para obter mais informações sobre o suporte à compreensão de linguagem no Bot Framework SDK, consulte Compreensão de linguagem natural.

C#

Em seguida, implementaremos a funcionalidade de telemetria no seu serviço LUIS. O serviço LUIS tem registro de telemetria integrado 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 IBotTelemetryClient telemetryClient parâmetro é necessário no FlightBookingRecognizer construtor em FlightBookingRecognizer.cs:

   public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
   

2. Em seguida, habilite o quando você criar o telemetryClient FlightBookingRecognizer no LuisRecognizer 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, você deve ter um bot funcional que registre dados de telemetria em insights de aplicativos. Você pode usar o Bot Framework Emulator para executar seu bot localmente. Você não deve ver nenhuma alteração no comportamento do bot, mas ele registrará informações no Application Insights. Interaja com o bot enviando várias mensagens e, na próxima seção, analisaremos os resultados da telemetria no Application Insights.

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

• Depurar um bot
• Diretrizes de teste e depuração
• Debug with the Emulator (Depurar com o Emulador)

JavaScript

Em seguida, implementaremos a funcionalidade de telemetria no seu serviço LUIS. O serviço LUIS tem registro de telemetria integrado 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 seu reconhecedor 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 seu 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, finalmente, você precisa incluir o telemetryClient ao criar uma instância do FlightBookingRecognizer em 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 seu bot localmente. Você não deve ver nenhuma alteração no comportamento do bot, mas ele registrará informações no Application Insights. Interaja com o bot enviando várias mensagens e a próxima seção descreve como revisar os resultados da telemetria no Application Insights.

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

• Depurar um bot
• Diretrizes de teste e depuração
• Debug with the Emulator (Depurar com o Emulador)

Visualizar seus dados de telemetria no Application Insights

O Application Insights monitora a disponibilidade, o desempenho e o uso do seu aplicativo de bot, seja ele hospedado na nuvem ou no local. Ele usa a poderosa plataforma de análise de dados no Azure Monitor para fornecer informações detalhadas sobre as operações do seu 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.

Consultando seus dados de telemetria no Application Insights usando consultas Kusto

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

Para consultar os seus dados

1. Aceda ao Portal do Azure

2. Para ir para a página do Application Insights, selecione Monitor, depois Aplicativos e encontre-o lá.

3. Uma vez no Application Insights, selecione Logs (Analytics).

   

4. Isso abrirá a janela Consulta. Insira a seguinte consulta 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á a porcentagem de caixas de diálogo em cascata que são executadas até a conclusão.

   

Gorjeta

Você pode fixar qualquer consulta ao painel do Application Insights selecionando o botão no canto superior direito da folha Logs (Analytics ). Basta selecionar o painel ao qual você deseja fixá-lo 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 novo painel será criado e associado automaticamente a ele. Você pode ver esse painel selecionando o botão na parte superior da folha do Application Insights, rotulado Painel do aplicativo.

Como alternativa, para exibir os dados, vá para 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 você fixou no seu painel.

Informações Adicionais

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