Add trace activities to your bot

APPLIES TO: SDK v4

A trace activity is an activity that your bot can send to the Bot Framework Emulator. You can use trace activities to interactively debug a bot, as they allow you to view information about your bot while it runs locally.

Trace activities are sent only to the Emulator and not to any other client or channel. The Emulator displays them in the log but not the main chat panel.

  • Trace activities sent via the turn context are sent through the send activity handlers registered on the turn context.
  • Trace activities sent via the turn context are associated with the inbound activity, by applying the conversation reference, if there was one. For a proactive message, the reply to ID will be a new GUID.
  • Regardless of how it is sent, a trace activity never sets the responded flag.

To use a trace activity

In order to see a trace activity in the Emulator, you need a scenario in which your bot will send a trace activity, such as throwing an exception and sending a trace activity from the adapter's on turn error handler.

To send a trace activity from your bot:

  1. Create a new activity.
    • Set its type property to "trace". This is required.
    • Optionally set its name, label, value, and value type properties, as appropriate for the trace.
  2. Use the turn context object's send activity method to send the trace activity.
    • This method adds values for the remaining required properties of the activity, based on the incoming activity. These include the channel ID, service URL, from, and recipient properties.

To view a trace activity in the Emulator:

  1. Run the bot locally on your machine.
  2. Test it using the Emulator.
    • Interact with the bot and use the steps in your scenario to generate the trace activity.
    • When your bot emits the trace activity, the trace activity is displayed in the Emulator log.

Here is a trace activity you might see if you ran the Core bot without first setting up the QnAMaker knowledge base that the bot relies upon.

Screen shot of the Emulator

Add a trace activity to the adapter's on-error handler

The adapter's on turn error handler catches any otherwise uncaught exception thrown from the bot during a turn. This is a good place for a trace activity, as you can send a user-friendly message to the user and send debugging information about the exception to the Emulator.

This example code is from the Core Bot sample. See the complete sample in C# or JavaScript or Python. For Java the code below is from the SDK code Java.

The adapter's OnTurnError handler creates the trace activity to include the exception information and sends it to the Emulator.

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

Additional resources