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

適用対象: SDK v4

テレメトリ ログを使用すると、ボット アプリケーションは Application Insights などのテレメトリ サービスにイベント データを送信できます。 テレメトリは、最も使用されている機能を示し、望ましくない動作を検出し、可用性、パフォーマンス、使用状況を可視化することで、ボットに関する分析情報を提供します。

この記事では、Application Insights を使用してボットにテレメトリを実装する方法について説明します。 この記事には、次の内容が含まれます。

• ボットでテレメトリを接続し、Application Insights に接続するために必要なコード。
• ボットの ダイアログでテレメトリを有効にする方法。
• テレメトリを有効にして、Azure AI サービスなどの他のサービスから使用状況データをキャプチャする方法。
• Application Insights でテレメトリ データを視覚化する方法。

重要

テレメトリで個人を特定できる情報 (PII) を収集する可能性があるリージョン ボットの場合、Application Insights リソースと Azure Bot リソースは、ボットと同じリージョンに存在する必要があります。 リソースが異なるリージョンにある場合、PII はボットの地理的リージョンから離れる可能性があります。

前提条件

C#

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

注意

Application Insights サンプル コードは、CoreBot サンプル コードを基にして構築されました。 この記事では、テレメトリを組み込むための CoreBot サンプル コードの変更手順について説明します。 Visual Studio でフォローしている場合は、完了するまでに Application Insights サンプル コードが表示されます。

JavaScript

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

注意

Application Insights サンプル コードは、CoreBot サンプル コードを基にして構築されました。 この記事では、テレメトリを組み込むための CoreBot サンプル コードの変更手順について説明します。 Visual Studio Code でフォローしている場合は、完了するまでに Application Insights サンプル コードが表示されます。

ボットでテレメトリを有効にする

C#

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

重要

Application Insights アカウントをセットアップし、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 サンプル コードを更新してフォローしている場合は、 の using ステートメント Microsoft.Bot.Builder.Integration.AspNet.Core が 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() メソッドに追加されたミドルウェア コードを使用するようにアダプターに指示します。 これは、コンストラクターのパラメーター リストの AdapterWithErrorHandler.cs TelemetryInitializerMiddleware telemetryInitializerMiddleware パラメーターと Use(telemetryInitializerMiddleware); 、次に示すようにコンストラクター内の ステートメントを使用して行います。

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

6. また、 の using ステートメントAdapterWithErrorHandler.csの一覧に を追加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"
       }
   }
   

   注意

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

ヒント

CoreBot サンプル コードをフォローして更新している場合は、問題が発生した場合は 、Application Insights サンプル コード を参照できます。

これで、テレメトリがボット ダイアログに追加されました。 ボットを今すぐ実行すると、Application Insights にログに記録されていることがわかります。ただし、Azure AI サービスなどの統合テクノロジがある場合は、そのコードにも を TelemetryClient 追加する必要があります。

JavaScript

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

重要

Application Insights アカウントをセットアップし、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 にあるモジュール ApplicationInsightsTelemetryClient と TelemetryInitializerMiddlewarebotbuilder-applicationinsights への参照を追加します。 これを行うには、必要なパッケージをインポートするコードの直後に、 の index.js上部付近から次のコードを追加します。

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

   ヒント

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

4. インストルメンテーション キーをパラメーターとして受け取り、前に参照したモジュールを使用してテレメトリ クライアントを返す、 という名前getTelemetryClientのApplicationInsightsTelemetryClient末尾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 に移動して、応答時間、アプリの全体的な正常性、一般的な実行情報など、ログに記録されている内容を確認できます。

アクティビティ イベントと個人情報のログ記録を有効または無効にする

C#

アクティビティ ログを有効または無効にする

既定では、ボットがアクティビティを送受信するとき、TelemetryInitializerMiddleware は TelemetryLoggerMiddleware を使用してテレメトリをログに記録します。 アクティビティ ログでは、Application Insights リソースにカスタム イベント ログが作成されます。 必要に応じて、Startup.cs に登録するときに を false にTelemetryInitializerMiddleware設定logActivityTelemetryすることで、アクティビティ イベントのログ記録を無効にすることができます。

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

次に、ダイアログにテレメトリ機能を追加するために含める必要がある内容を確認します。 これにより、実行されるダイアログやそれぞれについての統計情報などの追加情報を取得できます。

JavaScript

アクティビティ ログを有効または無効にする

既定では、 TelemetryInitializerMiddleware は、 を使用 TelemetryLoggerMiddleware して、ボットがアクティビティを送受信するときにテレメトリをログに記録します。 アクティビティ ログでは、Application Insights リソースにカスタム イベント ログが作成されます。 必要に応じて、 に false TelemetryInitializerMiddleware を設定logActivityTelemetryしてアクティビティ イベントログを無効にし、index.jsに登録します。

次のコード スニペットはサンプル 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に を登録するときに、 パラメーターを logPersonalInformation から false に true 変更することで、これらのプロパティを TelemetryLoggerMiddleware ログに含 めることができます。

// 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 や QnA Maker などの他のサービスから使用状況データを取り込めるようにする

注意

Azure AI QnA Maker は、2025 年 3 月 31 日に廃止される予定です。 2022 年 10 月 1 日から、新しい QnA Maker リソースやナレッジ ベースを作成することはできません。 Azure AI Language の一部として、新しいバージョンの質問と回答機能が利用できるようになりました。

Azure AI Language の機能であるカスタム質問応答は、QnA Maker サービスの更新バージョンです。 Bot Framework SDK での質問と回答のサポートの詳細については、「 自然言語の理解」を参照してください。

注意

Language Understanding (LUIS) は、2025 年 10 月 1 日に廃止されます。 2023 年 4 月 1 日から、新しい LUIS リソースを作成することはできません。 Azure AI 言語の一部として、新しいバージョンの言語理解を利用できるようになりました。

Azure AI Language の機能である会話言語理解 (CLU) は、LUIS の更新バージョンです。 Bot Framework SDK での言語理解のサポートの詳細については、「 自然言語理解」を参照してください。

C#

次に、LUIS サービスにテレメトリ機能を実装します。 LUIS サービスには利用できるテレメトリ ログが組み込まれているため、LUIS からのテレメトリ データの取得を開始するために行う必要はほとんどありません。 QnA Maker 対応ボットでテレメトリを有効にする場合は、「QnA Maker ボットにテレメトリを追加する」を参照してください

1. FlightBookingRecognizer.cs の FlightBookingRecognizer コンストラクターには IBotTelemetryClient telemetryClient パラメーターが必要です。

   public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
   

2. 次に、 コンストラクターで をtelemetryClientLuisRecognizer作成するときに をFlightBookingRecognizer有効にします。 これを行うには、新しい LuisRecognizerOption として をtelemetryClient追加します。

   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 でテレメトリの結果を確認します。

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

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

JavaScript

次に、LUIS サービスにテレメトリ機能を実装します。 LUIS サービスには利用できるテレメトリ ログが組み込まれているため、LUIS からのテレメトリ データの取得を開始するために行う必要はほとんどありません。

LUIS 認識エンジンでテレメトリ クライアントを有効にするには:

1. FlightBookingRecognizer.js を開きます。

2. パラメーターを telemetryClient コンストラクターに FlightBookingRecognizer 渡します。

   constructor(config, telemetryClient) {
   

3. オブジェクトの telemetryClient フィールドを recognizerOptions コンストラクターに telemetryClient 渡される プロパティに FlightBookingRecognizer 設定します。完了すると、コンストラクターは次のように表示されます。

   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. 最後に、 で のtelemetryClientインスタンスFlightBookingRecognizerindex.jsを作成するときに を含める必要があります。

   const memoryStorage = new MemoryStorage();
   

それです;テレメトリ データを Application Insights に記録する機能ボットが必要です。 Bot Framework Emulator を使用して、ボットをローカルで実行できます。 ボットの動作には変化は見られませんが、Application Insights に情報が記録されます。 複数のメッセージを送信してボットと対話し、次のセクションでは Application Insights でテレメトリの結果を確認する方法について説明します。

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

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

テレメトリ データを Application Insights で視覚化する

Application Insights は、クラウドとオンプレミスのどちらでホストされているかにかかわらず、ボット アプリケーションの可用性、パフォーマンス、使用状況を監視します。 Azure Monitor の強力なデータ分析プラットフォームを使用して、アプリケーションの操作に関する詳細な分析情報を提供し、ユーザーがエラーを報告するのを待たずに診断します。 Application Insights によって収集されたテレメトリ データを表示するにはいくつかの方法があります。2 つの主要な方法は、クエリとダッシュボードを使用するというものです。

Kusto クエリを使って Application Insights でテレメトリ データのクエリを実行する

このセクションは、Application Insights でのログ クエリの使用方法を学ぶための開始点として使用してください。 ここでは、2 つの有用なクエリを示し、追加情報を含む他のドキュメントへのリンクを提供します。

データのクエリを実行するには、次のようにします。

1. Azure portal に移動します

2. Application Insights ページに移動するには、[ 監視]、[ アプリケーション] の順に選択し、そこで見つけます。

3. Application Insights に入ったら、[ ログ (分析)] を選択します。

   

4. これにより、クエリ ウィンドウが表示されます。 次のクエリを入力し、 [実行] を選択します。

   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. これにより、完了まで実行されるウォーターフォール ダイアログの割合が返されます。

   

ヒント

[ ログ (分析)] ブレードの右上にあるボタンを選択すると、任意のクエリを Application Insights ダッシュボードにピン留めできます。 ピン留めするダッシュボードを選択するだけで、次回そのダッシュボードにアクセスするとそれが使用可能になります。

Application Insights ダッシュボード

Azure で Application Insights リソースを作成するたびに、新しいダッシュボードが自動的に作成されて、関連付けられます。 そのダッシュボードを表示するには、Application Insights ブレードの上部にある、 [アプリケーション ダッシュボード] というラベルの付いたボタンを選択します。

あるいは、データを表示するには、Azure portal に移動します。 左側の [ ダッシュボード ] を選択し、ドロップダウンから目的のダッシュボードを選択します。

ここには、ボットのパフォーマンスに関する既定の情報と、ダッシュボードにピン留めしたその他のクエリが表示されます。

追加情報

• QnA Maker ボットにテレメトリを追加する
• Application Insights とは何か?
• Application Insights の検索の使用
• Azure Application Insights を使ってカスタム KPI ダッシュボードを作成する