ボットへのトレース アクティビティの追加

この記事の対象: SDK v4

トレース アクティビティ は、ボットが Bot Framework Emulator に送信できるアクティビティです。 トレース アクティビティを使用すると、ボットをローカルで実行している間に情報を表示することができるため、ボットをインタラクティブにデバッグできます。

トレース アクティビティはエミュレーターにのみ送信され、他のクライアントまたはチャネルには送信されません。 エミュレーターでは、メインのチャット パネルではなく、ログに表示されます。

• ターン コンテキストを介して送信されたトレース アクティビティは、ターン コンテキストに登録された送信アクティビティ ハンドラーを介して送信されます。
• ターン コンテキストを介して送信されたトレース アクティビティは、会話リファレンスがあった場合にそれを適用し、受信アクティビティに関連付けられています。 プロアクティブ メッセージの場合、[reply to ID]\(返信先 ID) は新しい GUID になります。
• トレース アクティビティでは、送信方法に関係なく、[responded] フラグが設定されることはありません。

Note

Bot Framework JavaScript SDK、C#、Python SDK は引き続きサポートされますが、Java SDK については、最終的な長期サポートは 2023 年 11 月に終了する予定です。

Java SDK を使用して構築された既存のボットは引き続き機能します。

新しいボットを構築する場合は、Microsoft Copilot Studio の使用をご検討ください。また、適切なコパイロット ソリューションの選択に関する記事もお読みください。

詳細については、「The future of bot building」をご覧ください。

トレース アクティビティを使用するには

エミュレーターでトレース アクティビティを表示するには、例外をスローし、アダプターのオン ターン エラー ハンドラーからトレース アクティビティを送信するなど、ボットがトレース アクティビティを送信するシナリオが必要です。

ボットからトレース アクティビティを送信するには:

1. 新しいアクティビティを作成します。
   • 必須の type プロパティを "trace" に設定します。
   • 必要に応じて、トレースに対応する、name、label、value、および value type プロパティを設定します。
2. turn context オブジェクトの send activity メソッドを使用して、トレース アクティビティを送信します。
   • このメソッドは、受信アクティビティに基づいて、アクティビティの残りの必須プロパティの値を追加します。 これらのプロパティには、channel ID、service URL、from、および recipient プロパティが含まれます。

エミュレーターでトレース アクティビティを表示するには:

1. お使いのマシン上でローカルでボットを実行します。
2. エミュレーターを使ってテストします。
   • ボットと対話し、シナリオのステップを使用してトレース アクティビティを生成します。
   • ボットがトレース アクティビティを出力すると、トレース アクティビティがエミュレーター ログに表示されます。

ここでは、ボットが依存している QnAMaker ナレッジ ベースを最初に設定することなく、コアボットを実行した場合に表示されるトレース アクティビティを示します。

アダプターのオンエラー ハンドラーにトレース アクティビティを追加する

アダプターの オン ターン エラー ハンドラーは、ターン中にボットからスローされ、その他の方法ではキャッチされない例外をキャッチします。 エラー ハンドラーは、わかりやすいメッセージをユーザーに送信し、例外に関するデバッグ情報を Emulator に送信できるため、トレース アクティビティに適しています。

このコード例は、コア ボット サンプルからのものです。 C#、JavaScript、Python、または Java の完全なサンプルをご覧ください。

C#

アダプターの OnTurnError ハンドラーは、例外情報を含むトレース アクティビティを作成して、エミュレーターに送信します。

AdapterWithErrorHandler.cs

    {
        // Log any leaked exception from the application.
        // NOTE: In production environment, you should consider logging this to
        // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
        // to add telemetry capture to your bot.
        logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

        // Send a message to the user
        var errorMessageText = "The bot encountered an error or bug.";
        var errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.IgnoringInput);
        await turnContext.SendActivityAsync(errorMessage);

        errorMessageText = "To continue to run this bot, please fix the bot source code.";
        errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.ExpectingInput);
        await turnContext.SendActivityAsync(errorMessage);

        if (conversationState != null)
        {
            try
            {
                // Delete the conversationState for the current conversation to prevent the
                // bot from getting stuck in a error-loop caused by being in a bad state.
                // ConversationState should be thought of as similar to "cookie-state" in a Web pages.
                await conversationState.DeleteAsync(turnContext);
            }
            catch (Exception e)
            {
                logger.LogError(e, $"Exception caught on attempting to Delete ConversationState : {e.Message}");
            }
        }

        // Send a trace activity, which will be displayed in the Bot Framework Emulator
        await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
    };
}

JavaScript

アダプターの onTurnError ハンドラーは、例外情報を含むトレース アクティビティを作成して、エミュレーターに送信します。

index.js

    // Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.sendTraceActivity(
        'OnTurnError Trace',
        `${ error }`,
        'https://www.botframework.com/schemas/error',
        'TurnError'
    );

    // Send a message to the user
    let onTurnErrorMessage = 'The bot encountered an error or bug.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    onTurnErrorMessage = 'To continue to run this bot, please fix the bot source code.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    // Clear out state
    await conversationState.delete(context);
};

// Set the onTurnError for the singleton CloudAdapter.
adapter.onTurnError = onTurnErrorHandler;

// Define a state store for your bot. See https://aka.ms/about-bot-state to learn more about using MemoryStorage.
// A bot requires a state store to persist the dialog and user state between messages.

// For local development, in-memory storage is used.

Java

Java SDK では、AdapterWithErrorHandler クラスは com.microsoft.bot.integration パッケージ内の SDK の一部として含まれています。 アダプターの onTurnError ハンドラーは、例外情報を含むトレース アクティビティを作成して、エミュレーターに送信します。 既定のアダプターのソース コードを以下に示します。

AdapterWithErrorHandler.java

setOnTurnError((turnContext, exception) -> {
    LoggerFactory.getLogger(AdapterWithErrorHandler.class).error("onTurnError", exception);


    return turnContext.sendActivities(
        MessageFactory.text(ERROR_MSG_ONE), MessageFactory.text(ERROR_MSG_TWO)
    ).thenCompose(resourceResponse -> sendTraceActivity(turnContext, exception))
        .thenCompose(stageResult -> {
            if (withConversationState != null) {
                // Delete the conversationState for the current conversation to prevent the
                // bot from getting stuck in a error-loop caused by being in a bad state.
                // ConversationState should be thought of as similar to "cookie-state" in a
                // Web pages.
                return withConversationState.delete(turnContext)
                    .exceptionally(deleteException -> {
                        LoggerFactory.getLogger(AdapterWithErrorHandler.class)
                            .error("ConversationState.delete", deleteException);
                        return null;
                    });
            }
            return CompletableFuture.completedFuture(null);
        });
});

Python

アダプターの on_error ハンドラーは、例外情報を含むトレース アクティビティを作成して、エミュレーターに送信します。

adapter_with_error_handler.py

# This check writes out errors to console log
# NOTE: In production environment, you should consider logging this to Azure
#       application insights.
print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
traceback.print_exc()

# Send a message to the user
await context.send_activity("The bot encountered an error or bug.")
await context.send_activity(
    "To continue to run this bot, please fix the bot source code."
)
# Send a trace activity if we're talking to the Bot Framework Emulator
if context.activity.channel_id == "emulator":
    # Create a trace activity that contains the error object
    trace_activity = Activity(
        label="TurnError",
        name="on_turn_error Trace",
        timestamp=datetime.utcnow(),
        type=ActivityTypes.trace,
        value=f"{error}",
        value_type="https://www.botframework.com/schemas/error",
    )
    # Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.send_activity(trace_activity)

次のステップ

• 検査ミドルウェアを使用してボットをデバッグする方法では、トレース アクティビティを出力するミドルウェアを追加する方法について説明します。
• デプロイされたボットをデバッグする場合は、Application Insights を使用できます。 詳細については、「ボットへのテレメトリの追加」を参照してください。
• アクティビティの種類の詳細については、ボットのフレームワークのアクティビティ スキーマに関するページをご覧ください。