次の方法で共有

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

  • [アーティクル]

この記事の対象: SDK v4

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

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

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

重要

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

前提条件

Note

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

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

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

重要

Application Insights アカウントをセットアップし、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;
    ...
}

ヒント

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

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

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

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

既定では、ボットがアクティビティを送受信するとき、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);
            });
    ...
}

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

テレメトリが LUIS や QnA Maker などの他のサービスから使用状況データを取り込めるようにする

Note

Azure AI QnA Maker は 2025 年 3 月 31 日に廃止されます。 2022 年 10 月 1 日以降、新しい QnA Maker リソースまたはナレッジ ベースを作成できなくなります。 Azure AI Language の一部として、質問応答機能の新しいバージョンが提供されました。

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

Note

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

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

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

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

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

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

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

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

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

  1. Azure portal に移動します

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

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

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

    App Insights クエリのサンプル出力。

ヒント

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

Application Insights ダッシュボード

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

ボットの Application Insights ページにある [アプリケーション ダッシュボード] ボタンのスクリーンショット。

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

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

追加情報