QnAMaker ボットへのテレメトリの追加Add telemetry to your QnAMaker 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.

QnA Maker 対応ボットでテレメトリのログ記録を有効にする 2 つの新しいコンポーネントが Bot Framework SDK に追加されました。TelemetryLoggerMiddlewareQnAMaker クラスです。Two new components were added to the Bot Framework SDK that enable telemetry logging in QnA Maker enabled bots: TelemetryLoggerMiddleware and the QnAMaker class. TelemetryLoggerMiddleware は、メッセージが受信、送信、更新、または削除されるたびにログを記録するミドルウェア コンポーネントであり、"QnAMaker" クラスは、テレメトリ機能を拡張するカスタムのログ記録を提供します。TelemetryLoggerMiddleware is a middleware component that logs every time messages are received, sent, updated, or deleted, and the 'QnAMaker' class provides custom logging that extends telemetry capabilities.

この記事では、以下について説明します。In this article you will learn about:

  • ボットにテレメトリを実装するために必要なコードThe code required to wire up telemetry in your bot

  • すぐに使用できる QnA ログ記録と、標準のイベント プロパティを使用するレポートを有効にするために必要なコード。The code required to enable the out-of-the-box QnA logging and reports that use the standard event properties.

  • 幅広いレポートのニーズに応えるために、SDK の既定のイベント プロパティを変更または拡張する方法。Modifying or extending the SDK's default event properties to enable a wide range of reporting needs.

前提条件Prerequisites

注意

この記事では、テレメトリを組み込むために必要な手順について、QnA Maker サンプル コードに基づいて説明します。This article will build on the QnA Maker sample code by stepping you through the steps required to incorporate telemetry.

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

QnA Maker サンプル アプリを出発点に、QnA サービスを使用してテレメトリをボットに統合するために必要なコードを追加します。We will start with the QnA Maker sample app and add the code required to integrate telemetry into a bot using the QnA service. これにより、Application Insights は要求の追跡を開始できるようになります。This will enable Application Insights to begin tracking requests.

  1. Visual Studio で QnA Maker サンプル アプリを開きますOpen the QnA Maker 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;
    

    注意

    QnA Maker サンプル コードを更新して作業を進めている場合は、Microsoft.Bot.Builder.Integration.AspNet.Core の using ステートメントが既に QnA Maker サンプルにあることに気付きます。If you're following along by updating the QnA Maker sample code you will notice that the using statement for Microsoft.Bot.Builder.Integration.AspNet.Core already exists in the QnA Maker sample.

  4. Startup.cs で、ConfigureServices() メソッドに次のコードを追加します。Add the following code to the ConfigureServices() method in Startup.cs. こうすることで、依存関係の挿入 (DI) によりテレメトリ サービスをボットで使用できるようになります。This makes 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();
    
        // Add the standard telemetry client
        services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>();
    
        // Create the telemetry middleware to track conversation events
        services.AddSingleton<TelemetryLoggerMiddleware>();
    
        // Add the telemetry initializer middleware
        services.AddSingleton<IMiddleware, TelemetryInitializerMiddleware>();
    
        // 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>();
        ...
    }
    

    注意

    QnA Maker サンプル コードを更新して作業を進めている場合は、services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); が既に存在していることに気付きます。If you are following along by updating the QnA Maker 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 を開き、IMiddleware middleware をコンストラクターのパラメーター リストに追加します。Open AdapterWithErrorHandler.cs and add IMiddleware middleware to the constructors parameter list. Use(middleware); ステートメントをコンストラクターの最後の行として追加します。Add the Use(middleware); statement as the last line in the contructor:

    public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
            : base(credentialProvider)
    {
        ...
    
        Use(middleware);
    }
    
  6. appsettings.json ファイルで、Application Insights のインストルメンテーション キーを追加します。Add the Application Insights instrumentation key in your appsettings.json file. appsettings.json ファイルには、ボットの実行中に使用される外部サービスに関するメタデータが格納されます。The appsettings.json file contains metadata about external services the Bot uses while running. たとえば、CosmosDB、Application Insights、QnA Maker サービスの接続とメタデータがそこに保存されています。For example, CosmosDB, Application Insights and the QnA Maker service connection and metadata is stored there. appsettings.json ファイルへの追加は、次の形式にする必要があります。The addition to your appsettings.json file must be in this format:

    {
        "MicrosoftAppId": "",
        "MicrosoftAppPassword": "",
        "QnAKnowledgebaseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "QnAEndpointKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "QnAEndpointHostName": "https://xxxxxxxx.azurewebsites.net/qnamaker",
        "ApplicationInsights": {
            "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }
    }
    

    注意

    • Application Insights のインストルメンテーション キー の取得の詳細については、「Application Insights キー」の記事をご覧ください。Details on getting the Application Insights instrumentation key can be found in the article Application Insights keys.
    • Qna maker アカウントを既に持っている必要があります。必要に応じて、キー管理の記事で Qna のナレッジベース Id、エンドポイントキー、およびホスト名の値を取得する方法についての情報を参照してください。You should already have a QnA maker account, if needed you can find information on getting the QnA Knowledgebase Id, Endpoint Key and HostName values in the key management article.

この時点で、Application Insights を使用してテレメトリを有効にする準備作業が完了しました。At this point the preliminary work to enable telemetry using Application Insights is done. Bot Emulator を使用して bot をローカルで実行し、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.

ヒント

アクティビティ イベントおよび個人情報のログ記録の有効化または無効化の詳細については、「ボットへのテレメトリの追加」を参照してください。For information on Enabling / disabling activity event and personal information logging see Add telemetry to your bot

次に、テレメトリ機能を QnA Maker サービスに追加するために含める必要があるものを確認します。Next we will see what needs to be included to add telemetry functionality to the QnA Maker service.

テレメトリが QnA Maker サービスから使用状況データを取り込めるようにするEnabling telemetry to capture usage data from the QnA Maker service

QnA Maker サービスでは、組み込みのテレメトリ ログ記録が利用できるため、QnA Maker からのテレメトリ データの取得を開始するために実行しなければならない操作はほとんどありません。The QnA Maker service has built-in telemetry logging available so there is very little you need to do to start getting telemetry data from QnA Maker. まず、テレメトリを QnA Maker コードに組み込んで、組み込みのテレメトリのログ記録を有効にする方法について説明します。次に、レポートのさまざまなニーズを満たすために、既存のイベント データのプロパティを置き換える、またはプロパティを追加する方法について説明します。First we will see how to incorporate telemetry into the QnA Maker code to enable the built-in telemetry logging, then we will learn how to replace or add additional properties to the existing event data to satisfy a wide range of reporting needs.

既定の QnA ログ記録の有効化Enabling default QnA logging

  1. IBotTelemetryClient 型の private の読み取り専用フィールドを QnABot.csQnABot クラスに作成します。Create a private readonly field of type IBotTelemetryClient in your QnABot class in QnABot.cs:

    public class QnABot : ActivityHandler
        {
            private readonly IBotTelemetryClient _telemetryClient;
            ...
    }
    
  2. QnABot.csQnABot クラスのコンストラクターに IBotTelemetryClient パラメーターを追加し、前の手順で作成した private フィールドにその値を割り当てます。Add an IBotTelemetryClient parameter to your QnABot class constructor in QnABot.cs and assign its value to the private field created in the previous step:

    public QnABot(IConfiguration configuration, ILogger<QnABot> logger, IHttpClientFactory httpClientFactory, IBotTelemetryClient telemetryClient)
    {
        ...
        _telemetryClient = telemetryClient;
    }
    
  3. telemetryClient パラメーターは、QnABot.cs で新しい QnAMaker オブジェクトをインスタンス化するときに必要です。The telemetryClient parameter is required when instantiating the new QnAMaker object in QnABot.cs:

    var qnaMaker = new QnAMaker(new QnAMakerEndpoint
                {
                    KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                    EndpointKey = _configuration["QnAEndpointKey"],
                    Host = _configuration["QnAEndpointHostName"]
                },
                null,
                httpClient,
                _telemetryClient);
    

    ヒント

    エントリで使用するプロパティ名が、ファイルの AppSettings.jsで使用したプロパティ名と一致していることを確認 _configuration し、QnA Maker ポータルの [自分のナレッジベース] ページの [コードの表示] ボタンを選択して、これらのプロパティの値を取得します。Make sure that the property names that you use in the _configuration entries match the property names you used in the AppSettings.json file and the values for those properties are obtained by selecting the View Code button on the My knowledge bases page in the QnA Maker portal:

    AppSettings

QnA Maker の既定のエントリからログに記録されたテレメトリ データを表示するViewing Telemetry data logged from the QnA Maker default entries

次の手順を実行して、bot Emulator で bot を実行した後に Application Insights で QnA Maker bot の使用状況の結果を表示できます。You can view the results of your QnA Maker bot usage in Application Insights after running your bot in the bot Emulator by taking the following steps :

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

  2. [Monitor] (監視) > [アプリケーション] をクリックして Application Insights に移動します。Navigate to your Application Insights by clicking on Monitor > Applications.

  3. Application Insights を開いたら、次に示すように、ナビゲーション バーにある [Logs (Analytics)](ログ (分析)) をクリックします。Once in your Application Insights, click on Logs (Analytics) on the navigation bar as shown below:

    Log Analytics

  4. 次の Kusto クエリを入力して [実行] を選択しますEnter the following Kusto query and then select Run

    customEvents
    | where name == 'QnaMessage'
    | extend answer = tostring(customDimensions.answer)
    | summarize count() by answer
    
  5. このページはブラウザーで開いたままにしておきます。新しいカスタム プロパティを追加した後、このページに戻ります。Leave this page open in your browser, we will come back to it after adding a new custom property.

ヒント

Azure Monitor でログ クエリの記述に使用する Kusto クエリ言語はあまり知らないが SQL クエリ言語には詳しい方には、SQL と Azure Monitor ログ クエリの対応早見表が役立つことがあります。If you are new to the Kusto query language that is used to write log queries in Azure Monitor, but are familiar with SQL query language, you may find the SQL to Azure Monitor log query cheat sheet useful.

既定のイベント プロパティの変更または拡張Modifying or extending the default event properties

QnAMaker クラスで定義されていないプロパティが必要な場合、2 つの対処法がありますが、どちらの場合も QnAMaker クラスから派生した独自のクラスを作成する必要があります。If you need properties that are not defined in the QnAMaker class there are two ways of handling this, both require creating your own class derived from the QnAMaker class. 最初の方法では、後出の「プロパティの追加」で説明しているように、既存の QnAMessage イベントにプロパティを追加します。The first is explained in the section below titled Adding properties in which you add properties to the existing QnAMessage event. 2 番目の方法では、「カスタム プロパティを持つ新しいイベントの追加」で説明しているように、プロパティの追加が可能な新しいイベントを作成します。The second method allows you to create new events to which you can add properties as described in Adding new events with custom properties.

注意

QnAMessage イベントは Bot Framework SDK に含まれており、Application Insights のログに記録される、すぐに使用できるイベント プロパティをすべて提供します。The QnAMessage event is part of the Bot Framework SDK and provides all of the out-of-the-box event properties that are logged to Application Insights.

プロパティの追加Adding properties

次に示すのは、QnAMaker クラスから派生する方法の例です。The following demonstrates how you can derive from the QnAMaker class. この例では、"MyImportantProperty" プロパティを QnAMessage イベントに追加しています。The example shows adding the property "MyImportantProperty" to the QnAMessage event. QnAMessage イベントは、QnA の GetAnswers 呼び出しが実行されるたびにログに記録されます。The QnAMessage event is logged every time a QnA GetAnswers call is performed.

カスタム プロパティの追加方法を習得したら、新しいカスタム イベントを作成してプロパティをそれに関連付ける方法を学び、Bot Framework エミュレーターを使用してローカルでボットを実行し、Application Insights のログに記録された内容を Kusto クエリ言語を使用して確認します。After learning how to add custom properties we will learn how to create a new custom event and associate properties with it, then we will run the bot locally using the Bot Framework Emulator and see what is being logged in Application Insights using the Kusto query language.

  1. QnAMaker クラスを継承する MyQnAMaker という名前の新しいクラスを Microsoft.BotBuilderSamples 名前空間に作成し、MyQnAMaker.cs という名前で保存します。Create a new class named MyQnAMaker in the Microsoft.BotBuilderSamples namespace that inherits from the QnAMaker class and save it as MyQnAMaker.cs. QnAMaker クラスを継承するには、Microsoft.Bot.Builder.AI.QnA の using ステートメントを追加する必要があります。In order to inherit from the QnAMaker class you will need to add the Microsoft.Bot.Builder.AI.QnA using statement. コードは次のようになります。Your code should appear as follows:

    using Microsoft.Bot.Builder.AI.QnA;
    
    namespace Microsoft.BotBuilderSamples
    {
        public class MyQnAMaker : QnAMaker
        {
    
        }
    }
    
  2. クラスのコンストラクターを MyQnAMaker に追加します。Add a class constructor to MyQnAMaker. コンストラクターの System.Net.Http および Microsoft.Bot.Builder パラメーターに対して 2 つの using ステートメントが追加で必要になることに注意してください。Note that you will need two additional using statements for the constructors parameters System.Net.Http and Microsoft.Bot.Builder:

    ...
    using Microsoft.Bot.Builder.AI.QnA;
    using System.Net.Http;
    using Microsoft.Bot.Builder;
    
    namespace Microsoft.BotBuilderSamples
    {
        public class MyQnAMaker : QnAMaker
        {
            public MyQnAMaker(
                QnAMakerEndpoint endpoint,
                QnAMakerOptions options = null,
                HttpClient httpClient = null,
                IBotTelemetryClient telemetryClient = null,
                bool logPersonalInformation = false)
                : base(endpoint, options, httpClient, telemetryClient, logPersonalInformation)
            {
    
            }
        }
    }
    
  3. コンストラクターの後に、新しいプロパティを QnAMessage イベントに追加し、ステートメント System.Collections.GenericSystem.Threading、および System.Threading.Tasks をインクルードします。Add the new property to the QnAMessage event after the constructor and include the statements System.Collections.Generic, System.Threading, and System.Threading.Tasks:

    using Microsoft.Bot.Builder.AI.QnA;
    using System.Net.Http;
    using Microsoft.Bot.Builder;
    using System.Collections.Generic;
    using System.Threading;
    using System.Threading.Tasks;
    
    namespace Microsoft.BotBuilderSamples
    {
            public class MyQnAMaker : QnAMaker
            {
            ...
    
            protected override async Task OnQnaResultsAsync(
                                QueryResult[] queryResults,
                                Microsoft.Bot.Builder.ITurnContext turnContext,
                                Dictionary<string, string> telemetryProperties = null,
                                Dictionary<string, double> telemetryMetrics = null,
                                CancellationToken cancellationToken = default(CancellationToken))
            {
                var eventData = await FillQnAEventAsync(
                                        queryResults,
                                        turnContext,
                                        telemetryProperties,
                                        telemetryMetrics,
                                        cancellationToken)
                                    .ConfigureAwait(false);
    
                // Add new property
                eventData.Properties.Add("MyImportantProperty", "myImportantValue");
    
                // Log QnAMessage event
                TelemetryClient.TrackEvent(
                                QnATelemetryConstants.QnaMsgEvent,
                                eventData.Properties,
                                eventData.Metrics
                                );
            }
    
        }
    }
    
  4. 新しいクラスを使用するようにボットを変更します。QnABot.cs で、QnAMaker オブジェクトを作成する代わりに MyQnAMaker オブジェクトを作成します。Modify your bot to use the new class, instead of creating a QnAMaker object you will create a MyQnAMaker object in QnABot.cs:

    var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
                {
                    KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                    EndpointKey = _configuration["QnAEndpointKey"],
                    Host = _configuration["QnAEndpointHostName"]
                },
                null,
                httpClient,
                _telemetryClient);
    
新しいプロパティ MyImportantProperty からログに記録されたテレメトリ データの表示Viewing telemetry data logged from the new property MyImportantProperty

エミュレーターで bot を実行した後、次の手順に従って Application Insights で結果を表示できます。After running your bot in the Emulator you can view the results in Application Insights by doing the following:

  1. [Logs (Analytics)](ログ (分析)) ビューがアクティブになっているブラウザーに戻ります。Switch back to your browser that has the Logs (Analytics) view active.

  2. 次の Kusto クエリを入力して [実行] を選択します。Enter the following Kusto query and then select Run. これにより、新しいプロパティが実行された回数が表示されます。This will give a count of the number of times the new property was executed:

    customEvents
    | where name == 'QnaMessage'
    | extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
    | summarize count() by MyImportantProperty
    
  3. 回数の代わりに詳細を表示するには、最後の行を削除してクエリを再実行します。To show details instead of the count remove the last line and re-run the query:

    customEvents
    | where name == 'QnaMessage'
    | extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
    

カスタム プロパティを持つ新しいイベントの追加Adding new events with custom properties

QnaMessage 以外のイベントにデータのログを記録する必要がある場合、独自のプロパティを持つ独自のカスタム イベントを作成することができます。If you need to log data to a different event than QnaMessage, you can create your own custom event with its own properties. これを行うために、次のように MyQnAMaker クラスの最後にコードを追加します。To do this, we will add code to the end of the MyQnAMaker class as follows:

public class MyQnAMaker : QnAMaker
{
    ...

    // Create second event.
    var secondEventProperties = new Dictionary<string, string>();

    // Create new property for the second event.
    secondEventProperties.Add(
                        "MyImportantProperty2",
                        "myImportantValue2");

    // Log secondEventProperties event
    TelemetryClient.TrackEvent(
                    "MySecondEvent",
                    secondEventProperties);

}

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