将遥测功能添加到机器人

• CoreBot 示例代码
• Application Insights 示例代码
• Azure 订阅
• Application Insights 密钥
• 熟悉 Application Insights
• git

• CoreBot 示例代码
• Application Insights 示例代码
• Azure 订阅
• Application Insights 密钥
• 熟悉 Application Insights
• Visual Studio Code
• Node.js 10.14.1 或更高版本。 使用命令 node --version 确定节点的版本。
• Bot Framework Emulator

本文将从 CoreBot 示例应用着手，添加将遥测集成到任何机器人中所需的代码。 这样 Application Insights 就会开始跟踪请求。

1. 在 Visual Studio 中打开 CoreBot 示例应用。

2. 添加 Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet 包。 若要详细了解如何使用 NuGet，请参阅在 Visual Studio 中安装和管理包：

3. 在 Startup.cs 中包括以下语句：

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

   提示

   如果你是按原步骤操作并更新 CoreBot 示例代码，你会注意到 CoreBot 示例中已存在 Microsoft.Bot.Builder.Integration.AspNet.Core 的 using 语句。

4. 将以下代码包括到 Startup.cs 的 ConfigureServices() 方法中。 这样就可以通过依赖项注入 (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>();
       ...
   }
   

   提示

   如果你是按原步骤操作并更新 CoreBot 示例代码，你会注意到 services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); 已经存在。

5. 指示适配器使用已添加到 ConfigureServices() 方法的中间件代码。 在 AdapterWithErrorHandler.cs 中执行此操作时，参数 TelemetryInitializerMiddleware telemetryInitializerMiddleware 位于构造函数参数列表中，Use(telemetryInitializerMiddleware); 语句位于构造函数中，如下所示：

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

6. 你还需要将 Microsoft.Bot.Builder.Integration.ApplicationInsights.Core 添加到 AdapterWithErrorHandler.cs 中的 using 语句列表中。

7. 在 appsettings.json 文件中添加 Application Insights 检测密钥。 appsettings.json 文件包含有关机器人在运行时要使用的外部服务的元数据。 例如，Cosmos DB、Application Insights 和 Azure AI 服务连接和元数据就存储在其中。 添加到 appsettings.json 文件的内容必须采用以下格式：

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

   注意

   若要详细了解如何获取 Application Insights 检测密钥，可参阅 Application Insights 密钥一文。

目前，使用 Application Insights 启用遥测的初级工作已完成。 可以使用 Emulator 在本地运行机器人，然后转到 Application Insights 查看记录的内容，例如响应时间、整体应用运行状况和一般运行信息。

在机器人对话中启用遥测

将新对话添加到任何 ComponentDialog 时，它都将继承其父对话的 Microsoft.Bot.Builder.IBotTelemetryClient。 例如，在 CoreBot 示例应用程序中，所有对话都将添加到 MainDialog（属于 ComponentDialog）。 将 TelemetryClient 属性设置为 MainDialog 后，添加到该属性的所有对话都将自动从该属性继承 telemetryClient，因此在添加对话时无需显式设置该属性。

按照以下步骤更新 CoreBot 示例：

1. 在 MainDialog.cs 中，更新构造函数的参数列表，使其包含 IBotTelemetryClient 参数，然后将 MainDialog 的 TelemetryClient 属性设置为如下代码段所示的值：

   public MainDialog(IConfiguration configuration, ILogger<MainDialog> logger, IBotTelemetryClient telemetryClient)
       : base(nameof(MainDialog))
   {
       // Set the telemetry client for this and all child dialogs.
       this.TelemetryClient = telemetryClient;
       ...
   }
   

遥测现已添加到机器人对话。 如果现在运行机器人，应会看到 Application Insights 中记录了哪些内容；但是，如果有任何集成技术（如 Azure AI 服务），则还需要将 TelemetryClient 添加到代码。

本文将从 CoreBot 示例应用着手，添加将遥测集成到任何机器人中所需的代码。 这样 Application Insights 就会开始跟踪请求。

1. 在 Visual Studio Code 中打开 CoreBot 示例应用。

2. 将 Application Insights 密钥添加到 .env 文件：InstrumentationKey=<EnterInstrumentationKeyHere>。 .env 文件包含有关机器人在运行时要使用的外部服务的元数据。 例如，Application Insights 和 Azure AI 服务连接和元数据就存储在其中。 添加到 .env 文件的内容必须采用以下格式：

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

   注意

   若要详细了解如何获取 Application Insights 检测密钥，可参阅 Application Insights 密钥一文。

3. 添加对 Bot Framework SDK 的 botbuilder-applicationinsights 中的模块 ApplicationInsightsTelemetryClient 和 TelemetryInitializerMiddleware 的引用。 为此，请在 index.js 顶部附近紧接在用于导入所需包的代码后面添加以下代码：

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

   提示

   JavaScript 机器人示例使用遵循 CommonJS 模块系统的 Node.js，并使用内置的 require 函数来包含存在于单独文件中的模块。

4. 在 index.js 的末尾创建名为 getTelemetryClient 的新函数，该函数将检测密钥用作参数，并使用前面引用的 ApplicationInsightsTelemetryClient 模块返回一个遥测客户端。 此遥测客户端是遥测数据将发送到的位置，在本例中为 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. 接下来，需要将遥测中间件添加到适配器中间件管道。 为此，请紧接在错误处理代码后面添加以下代码：

   
   // 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. 要使对话报告遥测数据，它的 telemetryClient 必须与用于遥测中间件的对应项（即 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. 创建 restify HTTP Web 服务器对象后，指示它使用 bodyParser 处理程序。

       }
       return new NullTelemetryClient();
   }
   

   提示

   此代码使用了 restify bodyParser 函数。 restify“是一个 Node.js Web 服务框架，它已经过优化，可以生成语义正确的 RESTful Web 服务，供大规模生产使用。 Restify 针对内省和性能进行了优化，并用于地球上一些最大的 Node.js 部署。有关详细信息，请参阅 restify 网站。

   Node.js 遵循 CommonJS 模块系统，并使用内置 require 函数来包含存在于单独文件中的模块。

目前，使用 Application Insights 启用遥测的初级工作已完成。 可以使用 Emulator 在本地运行机器人，然后转到 Application Insights 查看记录的内容，例如响应时间、整体应用运行状况和一般运行信息。

启用或禁用活动日志记录

默认情况下，当机器人发送/接收活动时，TelemetryInitializerMiddleware 将使用 TelemetryLoggerMiddleware 来记录遥测数据。 活动日志记录在 Application Insights 资源中创建自定义事件日志。 如果需要，可以禁用活动事件日志记录，方法是在 Startup.cs 中注册 TelemetryInitializerMiddleware 时，将其上的 logActivityTelemetry 设置为 false。

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

启用或禁用个人信息日志记录

默认情况下，如果启用了活动日志记录，则传入/传出活动的某些属性将被排除在日志记录之外，因为它们可能包含个人信息，例如用户名和活动文本。 可以选择在日志记录中包含这些属性，方法是在注册 TelemetryLoggerMiddleware时，对 Startup.cs 进行以下更改。

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

接下来，我们将了解将遥测功能添加到对话中需要包含哪些内容。 这样你就可以获取其他信息，例如什么对话在运行，以及有关每个对话的统计信息。

启用或禁用活动日志记录

默认情况下，当机器人发送或接收活动时，TelemetryInitializerMiddleware 将使用 TelemetryLoggerMiddleware 来记录遥测数据。 活动日志记录在 Application Insights 资源中创建自定义事件日志。 如果需要，可以禁用活动事件日志记录，方法是在 index.js 中注册 TelemetryInitializerMiddleware 时，将其上的 logActivityTelemetry 设置为 false。

以下代码段取自示例 21.corebot-app-insights，显示了对 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();

以下代码段显示了需要在示例 21.corebot-app-insights 中对 TelemetryInitializerMiddleware 调用做出的更改，以禁用活动日志记录：

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

启用或禁用个人信息日志记录

默认情况下，如果启用了活动日志记录，则传入/传出活动的某些属性将被排除在日志记录之外，因为它们可能包含个人信息，例如用户名和活动文本。 可以选择将这些属性包含在日志记录中，方法是在 index.js 中注册 TelemetryLoggerMiddleware 时，将 logPersonalInformation 参数从 false 更改为 true。

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

接下来，我们将了解将遥测功能添加到对话中需要包含哪些内容。 这样你就可以获取其他信息，例如什么对话在运行，以及有关每个对话的统计信息。

接下来，我们将在 LUIS 服务中实现遥测功能。 LUIS 服务具有内置的遥测日志记录功能，因此无需执行任何操作即可开始从 LUIS 获取遥测数据。 如果有兴趣在启用了 QnA Maker 的机器人中启用遥测，请参阅将遥测数据添加到 QnA Maker 机器人

1. 在 FlightBookingRecognizer.cs 的 FlightBookingRecognizer 构造函数中，IBotTelemetryClient telemetryClient 参数是必需的：

   public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
   

2. 接下来，在 FlightBookingRecognizer 构造函数中创建 LuisRecognizer 时启用 telemetryClient。 通过将 telemetryClient 添加为新的 LuisRecognizerOption 来实现：

   if (luisIsConfigured)
   {
       var luisApplication = new LuisApplication(
           configuration["LuisAppId"],
           configuration["LuisAPIKey"],
           "https://" + configuration["LuisAPIHostName"]);
   
       // Set the recognizer options depending on which endpoint version you want to use.
       var recognizerOptions = new LuisRecognizerOptionsV3(luisApplication)
       {
           TelemetryClient = telemetryClient,
       };
       _recognizer = new LuisRecognizer(recognizerOptions);
   }
   

操作完毕。你现在应该有一个正常运行的机器人，可以将遥测数据记录到 Application Insights 中。 可以使用 Bot Framework Emulator 在本地运行机器人。 你应该看不到机器人的行为有任何变化，只会看到它将信息记录到 Application Insights 中。 通过发送多条消息与机器人进行交互，在下一节中，我们将在 Application Insights 中查看遥测结果。

若要了解如何测试和调试机器人，可参阅以下文章：

• 调试机器人
• 测试和调试指南
• 使用仿真器进行调试

接下来，我们将在 LUIS 服务中实现遥测功能。 LUIS 服务具有内置的遥测日志记录功能，因此无需执行任何操作即可开始从 LUIS 获取遥测数据。

若要在 LUIS 识别器中启用遥测客户端，请执行以下操作：

1. 打开FlightBookingRecognizer.js

2. 将 telemetryClient 参数传递给 FlightBookingRecognizer 构造函数：

   constructor(config, telemetryClient) {
   

3. 将 recognizerOptions 对象的 telemetryClient 字段设置为传递给 FlightBookingRecognizer 构造函数的 telemetryClient 属性，完成后，该构造函数将如下所示：

   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. 最后，需要在 index.js 中创建 FlightBookingRecognizer 的实例时包含 telemetryClient：

   const memoryStorage = new MemoryStorage();
   

操作完毕。你现在应该有一个正常运行的机器人，可以将遥测数据记录到 Application Insights 中。 可以使用 Bot Framework Emulator 在本地运行机器人。 你应该看不到机器人的行为有任何变化，只会看到它将信息记录到 Application Insights 中。 可以通过发送多条消息来与机器人交互。下一部分将介绍如何查看 Application Insights 中的遥测结果。

若要了解如何测试和调试机器人，可参阅以下文章：

• 调试机器人
• 测试和调试指南
• 使用仿真器进行调试