봇에 추적 활동 추가Add trace activities to your bot

적용 대상: SDK v4APPLIES TO: SDK v4

추적 활동 은 봇에서 Bot Framework Emulator에 보낼 수 있는 활동입니다.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.

추적 활동은 다른 클라이언트 또는 채널이 아닌 Emulator에만 보내집니다.Trace activities are sent only to the Emulator and not to any other client or channel. Emulator는 추적 활동을 로그에 표시하지만 기본 채팅 패널에는 표시하지 않습니다.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. 자동 관리 메시지의 경우 reply to ID(ID에 회신)는 새 GUID가 됩니다.For a proactive message, the reply to ID will be a new GUID.
  • 전송 방법에 관계없이 추적 활동은 responded(응답됨) 플래그를 설정하지 않습니다.Regardless of how it is sent, a trace activity never sets the responded flag.

추적 활동 사용To use a trace activity

Emulator에서 추적 활동을 보려면 봇에서 예외 throw 및 어댑터의 on turn error 처리기에서 추적 활동 보내기와 같은 추적 활동을 보내는 시나리오가 필요합니다.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.
    • type 속성을 "trace"로 설정합니다.Set its type property to "trace". 이것은 필수입니다.This is required.
    • 필요에 따라 name(이름), label(레이블), value(값) 및 value type(값 형식) 속성을 추적에 적합하게 설정합니다.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. 여기에는 channel ID(채널 ID), service URL(서비스 URL), from(보낸 사람), recipient(받는 사람) 속성이 포함됩니다.These include the channel ID, service URL, from, and recipient properties.

Emulator에서 추적 활동을 보려면 다음을 수행합니다.To view a trace activity in the Emulator:

  1. 봇을 머신에서 로컬로 실행합니다.Run the bot locally on your machine.
  2. Emulator를 사용하여 테스트합니다.Test it using the Emulator.
    • 봇과 상호 작용하고 시나리오의 단계를 사용하여 추적 활동을 생성합니다.Interact with the bot and use the steps in your scenario to generate the trace activity.
    • 봇에서 추적 활동을 내보내면 추적 활동이 Emulator 로그에 표시됩니다.When your bot emits the trace activity, the trace activity is displayed in the Emulator log.

봇에서 사용하는 QnAMaker 기술 자료를 먼저 설정하지 않고 코어 봇을 실행한 경우에 볼 수 있는 추적 활동은 다음과 같습니다.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.

Emulator의 스크린샷

어댑터의 on-error 처리기에 추적 활동 추가Add a trace activity to the adapter's on-error handler

어댑터의 on turn error 처리기는 턴 중에 봇에서 throw된 catch되지 않은 예외를 catch합니다.The adapter's on turn error handler catches any otherwise uncaught exception thrown from the bot during a turn. 이는 사용자에게 친숙한 메시지를 보내고 예외에 대한 디버깅 정보를 Emulator에 보낼 수 있으므로 추적 활동에 적합합니다.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. 전체 샘플은 C#, JavaScript 또는 Python에서 참조하세요.See the complete sample in C# or JavaScript or Python. Java의 경우 아래 코드는 SDK 코드 Java의 코드입니다.For Java the code below is from the SDK code Java.

어댑터의 OnTurnError 처리기는 예외 정보를 포함하는 추적 활동을 만들고 이를 Emulator에 보냅니다.The adapter's OnTurnError handler creates the trace activity to include the exception information and sends it to the Emulator.

AdapterWithErrorHandler.csAdapterWithErrorHandler.cs

OnTurnError = async (turnContext, exception) =>
{
    // 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