ボットへのテレメトリの追加Add telemetry to your bot

適用対象: SDK v4APPLIES TO: SDK v4

Bot Framework SDK のバージョン 4.2 にテレメトリのログ記録が追加されました。Telemetry logging was added to version 4.2 of the Bot Framework SDK. これにより、ボット アプリケーションは Application Insights などのテレメトリ サービスにイベント データを送信できます。This enables bot applications to send event data to telemetry services such as Application Insights. テレメトリは、どの機能が最も使用されているかを示すことによりボットの分析情報を提供し、不要な動作を検出し、可用性、パフォーマンス、および使用状況を可視化します。Telemetry offers insights into your bot by showing which features are used the most, detects unwanted behavior and offers visibility into availability, performance, and usage.

注意事項: バージョン 4.6 では、カスタム アダプターを使用するときにテレメトリが正しく記録されるように、ボットにテレメトリを実装するための標準的な方法が更新されました。この記事は更新され、更新された方法が表示されるようになりました。これらの変更は下位互換性があり、前の方法を使用するボットはテレメトリを正しくログに記録し続けます。Note: In version 4.6, the standard method for implementing telemetry into a bot has been updated in order to ensure telemetry is logged correctly when using a custom adapter. This article has been updated to show the updated method. The changes are backwards compatible and bots using the previous method will continue to log telemetry correctly.

この記事では、 を使用してボットにテレメトリを実装する方法についてApplication Insights。In this article you will learn how to implement telemetry into your bot using Application Insights. 次の情報を取り上けます。It will cover:

  • ボット内のテレメトリを接続し、ボットに接続するために必要なApplication Insights。The code required to wire up telemetry in your bot and connect to Application Insights.

  • ボットのダイアログでテレメトリを 有効にするEnabling telemetry in your bot's Dialogs.

  • テレメトリが LUISQnA Maker などの他のサービスから使用状況データを取り込めるようにするEnabling telemetry to capture usage data from other services like LUIS and QnA Maker.

  • テレメトリ データを視覚化する Application Insights。Visualizing your telemetry data in Application Insights.

注意

関連する Composer の記事「ボットのテレメトリをキャプチャ する」を参照してくださいYou may want to look at the related Composer article Capture your bot's telemetry.

前提条件Prerequisites

注意

Application Insights サンプル コードは、CoreBot サンプル コードを基にして構築されました。The Application Insights sample code was built on top of the CoreBot sample code. この記事では、テレメトリを組み込むための CoreBot サンプル コードの変更手順について説明します。This article will step you through modifying the CoreBot sample code to incorporate telemetry. この手順に従っている場合Visual Studio完了Application Insightsのサンプル コードが表示されます。If you are following along in Visual Studio you will have the Application Insights sample code by the time you are finished.

ボットでテレメトリを接続するWiring up telemetry in your bot

この記事は、 corebot サンプルアプリ から開始し、任意のボットにテレメトリを統合するために必要なコードを追加します。This article starts from the CoreBot sample app and adds the code required to integrate telemetry into any bot. これにより、Application Insights は要求の追跡を開始できるようになります。This will enable Application Insights to begin tracking requests.

重要

Application Insightsアカウントをセットアップしておらず、 Application Insights キーを作成していない場合は、先に進んでください。If you have not setup your Application Insights account and created your Application Insights key, do that before proceeding.

  1. Visual Studio で Corebot サンプルアプリ を開きます。Open the CoreBot sample app in Visual Studio.

  2. Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet パッケージを追加します。Add the Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet package. NuGet の使用方法について詳しくは、「Visual Studio にパッケージをインストールして管理する」を参照してください。For more information on using NuGet, see Install and manage packages in Visual Studio:

  3. 次のステートメントを Startup.cs に含めます。Include the following statements in 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 サンプルにあることに気付きます。Note: If you're following along by updating the CoreBot sample code you will notice that the using statement for Microsoft.Bot.Builder.Integration.AspNet.Core already exists in the CoreBot sample.

  4. 次のコードを Startup.csConfigureServices() メソッドに含めます。Include the following code in the ConfigureServices() method in Startup.cs. こうすることで、依存関係の挿入 (DI) によりテレメトリ サービスをボットで使用できるようになります。This will make telemetry services available to your bot via dependency injection (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>(); 既に存在していることがわかります。Note: If you're following along by updating the CoreBot sample code you will notice that services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); already exists.

  5. ConfigureServices() メソッドに追加されたミドルウェア コードを使用するようにアダプターに指示します。Instruct the adapter to use the middleware code that was added to the ConfigureServices() method. この操作は、次に AdapterWithErrorHandler.cs 示すように、コンストラクターのパラメーターリストで telemetryInitializerMiddleware TelemetryInitializerMiddleware パラメーターを指定し、コンストラクターのステートメントを使用して実行し Use(telemetryInitializerMiddleware); ます。You do this in AdapterWithErrorHandler.cs with the parameter TelemetryInitializerMiddleware telemetryInitializerMiddleware in the constructor's parameter list, and the Use(telemetryInitializerMiddleware); statement in the constructor as shown here:

        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 を追加する必要があります。You will also need to add Microsoft.Bot.Builder.Integration.ApplicationInsights.Core to your list of using statements in AdapterWithErrorHandler.cs.

  7. appsettings.json ファイルで、Application Insights のインストルメンテーション キーを追加します。Add the Application Insights instrumentation key in your appsettings.json file. ファイルには、 appsettings.json 実行中に bot が使用する外部サービスに関するメタデータが含まれています。The appsettings.json file contains metadata about external services the bot uses while running. たとえば、CosmosDB、Application Insights、Language Understanding (LUIS) サービスの接続とメタデータがそこに保存されています。For example, CosmosDB, Application Insights and the Language Understanding (LUIS) service connection and metadata is stored there. appsettings.json ファイルへの追加は、次の形式にする必要があります。The addition to your appsettings.json file must be in this format:

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

    注:Application Insights のインストルメンテーション キー の取得の詳細については、「Application Insights キー」の記事をご覧ください。Note: Details on getting the Application Insights instrumentation key can be found in the article Application Insights keys.

この時点で、Application Insights を使用してテレメトリを有効にする準備作業が完了しました。At this point the preliminary work to enable telemetry using Application Insights is done. Bot Emulator を使用してボットをローカルで実行し、Application Insights にアクセスして、応答時間、アプリ全体の正常性、一般的な実行情報など、ログに記録されている内容を確認できます。You can run your bot locally using the bot Emulator and then go into Application Insights to see what is being logged, such as response time, overall app health, and general running information.

ボットのダイアログでテレメトリを有効にするEnabling telemetry in your bots Dialogs

ComponentDialog に新しいダイアログを追加すると、その親ダイアログの Microsoft.Bot.Builder.IBotTelemetryClient が継承されます。When adding a new dialog to any ComponentDialog, it will inherit the Microsoft.Bot.Builder.IBotTelemetryClient of its parent dialog. たとえば、CoreBot サンプル アプリケーションでは、ComponentDialog である MainDialog にすべてのダイアログが追加されます。For example, In the CoreBot sample application all dialogs are added to the MainDialog which is a ComponentDialog. TelemetryClient プロパティを MainDialog に設定すると、そこに追加されたすべてのダイアログが、MainDialog から telemetryClient を自動的に継承します。ダイアログを追加する際に明示的に設定する必要はありません。Once you set the TelemetryClient property to the MainDialog all dialogs added to it will automatically inherit the telemetryClient from it, so it does not need to be explicitly set when adding dialogs.

次の手順に従って、CoreBot の例を更新します。Follow the steps below to update your CoreBot example:

  1. MainDialog.cs で、コンストラクターのパラメーター リストに IBotTelemetryClient パラメーターを追加し、MainDialog の TelemetryClient プロパティをその値に設定します。次のコード スニペットを参照してください。In MainDialog.cs, update the constructor's parameter list to include the IBotTelemetryClient parameter, then set the MainDialog's TelemetryClient property to that value as shown in the following code snippet:

    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 サンプル コードを参照できます。If you are following along and updating the CoreBot sample code, you can refer to the Application Insights sample code if you run into any problems.

ボット ダイアログへのテレメトリの追加についてはこれですべてです。この時点でボットを実行した場合は、Application Insights にログが記録されているのを確認できるはずです。ただし、LUIS や QnA Maker などの統合テクノロジがある場合は、さらに TelemetryClient をそのコードに追加する必要があります。That's all there is to adding telemetry to your bots dialogs, at this point if you ran your bot you should see things being logged in Application Insights, however if you have any integrated technology such as LUIS and QnA Maker you will need to add the TelemetryClient to that code as well.

アクティビティ イベントと個人情報のログ記録の有効化/無効化Enabling / disabling activity event and personal information logging

アクティビティのログ記録を有効または無効にするEnabling or disabling Activity logging

既定では、ボットがアクティビティを送受信するとき、TelemetryInitializerMiddlewareTelemetryLoggerMiddleware を使用してテレメトリをログに記録します。By default, the TelemetryInitializerMiddleware will use the TelemetryLoggerMiddleware to log telemetry when your bot sends / receives activities. アクティビティ ログでは、Application Insights リソースにカスタム イベント ログが作成されます。Activity logging creates custom event logs in your Application Insights resource. 必要に応じて、Startup.cs 内に登録する際に、TelemetryInitializerMiddlewarelogActivityTelemetry を false に設定して、アクティビティ イベントのログ記録を無効にできます。If you wish, you can disable activity event logging by setting logActivityTelemetry to false on the TelemetryInitializerMiddleware when registering it in 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);
            });
    ...
}

個人情報のログ記録を有効または無効にするEnable or disable logging personal information

既定では、アクティビティ ログが有効になっている場合、受信/送信アクティビティの一部のプロパティは、ユーザー名やアクティビティ テキストなどの個人情報が含まれる可能性があるため、ログから除外されます。By default, if activity logging is enabled, some properties on the incoming / outgoing activities are excluded from logging as they are likely to contain personal information, such as user name and the activity text. これらのプロパティをログに含めるには、TelemetryLoggerMiddleware の登録時に Startup.cs に次の変更を加える必要があります。You can choose to include these properties in your logging by making the following change to Startup.cs when registering the 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);
            });
    ...
}

次に、テレメトリ機能をダイアログに追加するために含める必要があるものを確認します。Next we will see what needs to be included to add telemetry functionality to the dialogs. これにより、実行されるダイアログやそれぞれについての統計情報などの追加情報を取得できます。This will enable you to get additional information such as what dialogs run, and statistics about each one.

テレメトリが LUIS や QnA Maker などの他のサービスから使用状況データを取り込めるようにするEnabling telemetry to capture usage data from other services like LUIS and QnA Maker

次に、LUIS サービスでテレメトリ機能を実装します。We will next implement telemetry functionality in your LUIS service. LUIS サービスでは、組み込みのテレメトリ ログ記録が利用できるため、LUIS からのテレメトリ データの取得を開始するために実行しなければならない操作はほとんどありません。The LUIS service has built-in telemetry logging available so there is very little you need to do to start getting telemetry data from LUIS. QnA Maker 対応ボットでテレメトリを有効にすることを検討している場合は、「QnAMaker ボットへのテレメトリの追加」を参照してくださいIf you are interested in enabling telemetry in a QnA Maker enabled bot, see Add telemetry to your QnAMaker bot

  1. FlightBookingRecognizer.csFlightBookingRecognizer コンストラクターには IBotTelemetryClient telemetryClient パラメーターが必要です。The IBotTelemetryClient telemetryClient parameter is required in the FlightBookingRecognizer constructor in FlightBookingRecognizer.cs:

    public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
    
  2. 次に、FlightBookingRecognizer コンストラクターで LuisRecognizer を作成する際に telemetryClient を有効にする必要があります。Next you will need to enable the telemetryClient when creating your LuisRecognizer in the FlightBookingRecognizer constructor. これを行うには、新しい telemetryClient LuisRecognizerOption として を追加しますYou do this by adding the telemetryClient as a new 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.
        // More details can be found in /azure/cognitive-services/luis/luis-migration-api-v3
        var recognizerOptions = new LuisRecognizerOptionsV3(luisApplication)
        {
            TelemetryClient = telemetryClient,
        };
        _recognizer = new LuisRecognizer(recognizerOptions);
    }
    

これで、テレメトリ データを Application insights に記録する、機能するボットが用意できたはずです。That's it, you should have a functional bot that logs telemetry data into Application insights. Bot Framework Emulator を使用して、ボットをローカルで実行できます。You can use the Bot Framework Emulator to run your bot locally. ボットの動作には変化は見られませんが、Application Insights に情報が記録されます。You shouldn't see any changes in the bot's behavior, but it will be logging information into Application Insights. 複数のメッセージを送信してボットと対話します。次のセクションでは、Application Insights でテレメトリの結果を確認します。Interact with the bot by sending multiple messages and in the next section we will review the telemetry results in Application Insights.

ボットのテストとデバッグの詳細については、次の記事を参照できます。For information on testing and debugging your bot, you can refer to the following articles:

テレメトリ データを Application Insights で視覚化するVisualizing your telemetry data in Application Insights

Application Insights は、クラウドとオンプレミスのどちらでホストされているかにかかわらず、ボット アプリケーションの可用性、パフォーマンス、使用状況を監視します。Application Insights monitors the availability, performance, and usage of your bot application whether it's hosted in the cloud or on-premises. Azure Monitor の強力なデータ分析プラットフォームを利用し、ユーザーの報告を待つことなく、アプリケーション運用やエラー診断に対する深い洞察を提供します。It leverages the powerful data analysis platform in Azure Monitor to provide you with deep insights into your application's operations and diagnose errors without waiting for a user to report them. Application Insights によって収集されたテレメトリ データを表示するにはいくつかの方法があります。2 つの主要な方法は、クエリとダッシュボードを使用するというものです。There are a few ways to see the telemetry data collected by Application Insights, two of the primary ways are through queries and the dashboard.

Kusto クエリを使って Application Insights でテレメトリ データのクエリを実行するQuerying your telemetry data in Application Insights using Kusto Queries

このセクションは、Application Insights でのログ クエリの使用方法を学ぶための開始点として使用してください。Use this section as a starting point to learn how to use log queries in Application Insights. ここでは、2 つの有用なクエリを示し、追加情報を含む他のドキュメントへのリンクを提供します。It demonstrates two useful queries and provides links to other documentation with additional information.

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

  1. Azure portal に移動しますGo to the Azure portal

  2. Application Insights に移動します。Navigate to your Application Insights. これを行う最も簡単な方法は、 [監視] > [アプリケーション] の順にクリックすることであり、そこで見つかります。Easiest way to do so is click on Monitor > Applications and find it there.

  3. Application Insights を開いたら、ナビゲーション バーにある [ログ (Analytics)] をクリックできます。Once in your Application Insights, you can click on Logs (Analytics) on the navigation bar.

    ログ (Analytics) LogView

  4. これにより、クエリ ウィンドウが表示されます。This will bring up the Query window. 次のクエリを入力し、 [実行] を選択します。Enter the following query and select Run:

    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. これにより、完了まで実行されるウォーターフォール ダイアログの割合が返されます。This will return the percentage of waterfall dialogs that run to completion.

    App Insights クエリの完了率

ヒント

[ログ (Analytics)] ブレードの右上にあるボタンを選択することにより、Application Insights ダッシュボードに任意のクエリをピン留めできます。You can pin any query to your Application Insights dashboard by selecting the button on the top right of the Logs (Analytics) blade. ピン留めするダッシュボードを選択するだけで、次回そのダッシュボードにアクセスするとそれが使用可能になります。Just select the dashboard you want it pinned to, and it will be available next time you visit that dashboard.

Application Insights ダッシュボードThe Application Insights dashboard

Azure で Application Insights リソースを作成するたびに、新しいダッシュボードが自動的に作成されて、関連付けられます。Anytime you create an Application Insights resource in Azure, a new dashboard will automatically be created and associated with it. そのダッシュボードを表示するには、Application Insights ブレードの上部にある、 [アプリケーション ダッシュボード] というラベルの付いたボタンを選択します。You can see that dashboard by selecting the button at the top of your Application Insights blade, labeled Application Dashboard.

アプリケーション ダッシュボード リンク

あるいは、データを表示するには、Azure portal に移動します。Alternatively, to view the data, go to the Azure portal. 左側の [ダッシュボード] をクリックし、目的のダッシュボードをドロップダウンから選択します。Click Dashboard on the left, then select the dashboard you want from the drop-down.

ここには、ボットのパフォーマンスに関する既定の情報と、ダッシュボードにピン留めしたその他のクエリが表示されます。There, you'll see some default information about your bot performance and any additional queries that you've pinned to your dashboard.

追加情報Additional Information