ボットへのテレメトリの追加

• CoreBot サンプル コード
• Application Insights サンプル コード
• Microsoft Azure のサブスクリプション。
• Application Insights のキー
• Application Insights を熟知していること
• git

• CoreBot サンプル コード
• Application Insights サンプル コード
• Microsoft Azure のサブスクリプション。
• Application Insights のキー
• Application Insights を熟知していること
• Visual Studio Code
• Node.js バージョン 10.14 以降。 コマンド node --version を使用して、使用しているノードのバージョンを確認します。
• Bot Framework Emulator

この記事では、CoreBot サンプル アプリから始まり、テレメトリを任意のボットに統合するために必要なコードを追加します。 これにより、Application Insights は要求の追跡を開始できるようになります。

1. Visual Studio Code で 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 サンプルコードを更新してフォローしている場合は、Microsoft.Bot.Builder.Integration.AspNet.Core の using ステートメントが CoreBot サンプルに既に存在していることがわかります。

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() メソッドに追加されたミドルウェア コードを使用するようにアダプターに指示します。 これは、コンストラクターのパラメーターリスト内のパラメーター TelemetryInitializerMiddleware telemetryInitializerMiddleware、および次に示すコンストラクター内の Use(telemetryInitializerMiddleware); ステートメントを使用して AdapterWithErrorHandler.cs で実行します。

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

6. また、AdapterWithErrorHandler.cs の using ステートメントのリストに Microsoft.Bot.Builder.Integration.ApplicationInsights.Core を追加する必要があります。

7. appsettings.json ファイルで、Application Insights のインストルメンテーション キーを追加します。 appsettings.json ファイルには、実行中にボットが使用する外部サービスに関するメタデータが含まれています。 たとえば、Cosmos DB、Application Insights、Azure AI サービスの接続とメタデータがそこに格納されます。 appsettings.json ファイルへの追加は、次の形式にする必要があります。

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

   Note

   Application Insights のインストルメンテーション キーの取得の詳細については、「Application Insights キー」の記事をご覧ください。

この時点で、Application Insights を使用してテレメトリを有効にする準備作業が行われます。 エミュレーターを使用してボットをローカルで実行し、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=
   

   Note

   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 Bot Samples では、CommonJS モジュール システムと、別のファイルに存在するモジュールを含める組み込み require 関数に従う Node.js を使用します。

4. インストルメンテーションキーをパラメーターとして受け取り、以前に参照した ApplicationInsightsTelemetryClient モジュールを使用してテレメトリクライアントを返す getTelemetryClient という名前の index.js の末尾に新しい関数を作成します。 このテレメトリ クライアントは、テレメトリ データの送信先 (この場合は 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();
   }
   

   ヒント

   これは restifybodyParser 関数を使用します。 restify は、「運用環境で大規模に使用できる意味的に正しい RESTful Web サービスを構築するために最適化されたNode.js Web サービス フレームワークです。 restify は、イントロスペクションとパフォーマンスを最適化し、地球上で最も大きな Node.js デプロイの一部で使用されます。」詳細については、restify Web サイトを参照してください。

   Node.js は CommonJS モジュール システムに従い、別のファイルに存在するモジュールを含める組み込み require 関数を使用します。

この時点で、Application Insights を使用してテレメトリを有効にする準備作業が行われます。 エミュレーターを使用してボットをローカルで実行し、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();

次のコード スニペットは、アクティビティ ログを無効にするために TelemetryInitializerMiddleware を呼び出す際にサンプル 21.corebot-app-insights で必要な変更を示しています。

// 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 でテレメトリの結果を確認する方法について説明します。

ボットのテストとデバッグの詳細については、次の記事を参照できます。

• ボットのデバッグ
• テストとデバッグのガイドライン
• エミュレーターを使用したデバッグ