Add trace activities to your bot


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's sent, a trace activity never sets the responded flag.


The Bot Framework JavaScript, C#, and Python SDKs will continue to be supported, however, the Java SDK is being retired with final long-term support ending in November 2023. Only critical security and bug fixes within this repository will be undertaken.

Existing bots built with the Java SDK will continue to function.

For new bot building, consider using Power Virtual Agents and read about choosing the right chatbot solution.

For more information, see The future of bot building.

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 required type property to "trace".
    • 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 properties 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's 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.

Screenshot of trace activity output in 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. The error handler 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#, JavaScript, Python, or Java.

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


        // Log any leaked exception from the application.
        // NOTE: In production environment, you should consider logging this to
        // Azure Application Insights. Visit 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)
                // 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, "", "TurnError");

Next steps