봇에 추적 활동 추가

적용 대상: SDK v4

추적 활동은 봇에서 Bot Framework Emulator에 보낼 수 있는 활동입니다. 추적 활동을 사용하여 봇이 로컬로 실행되는 동안 봇의 정보를 볼 수 있으므로 봇을 대화형으로 디버그할 수 있습니다.

추적 활동은 에뮬레이터에만 전송되고 다른 클라이언트 또는 채널에는 전송되지 않습니다. 에뮬레이터는 로그에 표시되지만 기본 채팅 패널에는 표시되지 않습니다.

• 턴 컨텍스트를 통해 전송된 추적 활동은 턴 컨텍스트에 등록된 송신 작업 처리기를 통해 전송됩니다.
• 턴 컨텍스트를 통해 전송된 추적 활동은 대화 참조가 있는 경우 대화 참조를 적용하여 인바운드 활동과 연결됩니다. 사전 메시지의 경우 ID에 대한 회신은 새 GUID가 됩니다.
• 전송 방법에 관계없이 추적 작업은 응답된 플래그를 설정하지 않습니다.

참고 항목

Bot Framework JavaScript, C#및 Python SDK는 계속 지원되지만 Java SDK는 2023년 11월에 종료되는 최종 장기 지원으로 사용 중지됩니다.

Java SDK를 사용하여 빌드된 기존 봇은 계속 작동합니다.

새 봇 빌드의 경우 Microsoft Copilot Studio를 사용하고 올바른 부조종사 솔루션 선택에 대해 알아봅니다.

자세한 내용은 봇 빌드의 미래를 참조 하세요.

추적 활동 사용

에뮬레이터에서 추적 작업을 보려면 봇이 예외를 throw하고 어댑터의 켜기 오류 처리기에서 추적 작업을 보내는 등의 추적 작업을 보내는 시나리오가 필요합니다.

봇에서 추적 작업을 보내려면 다음을 수행합니다.

1. 새 활동을 만듭니다.
   • 필수 형식 속성을 "trace"로 설정합니다.
   • 필요에 따라 추적에 적합한 이름, 레이블, 값 및 값 형식 속성을 설정합니다.
2. 턴 컨텍스트 개체의 활동 보내기 메서드를 사용하여 추적 활동을 보냅니다.
   • 이 메서드는 들어오는 활동에 따라 활동의 나머지 필수 속성에 대한 값을 추가합니다. 이러한 속성에는 채널 ID, 서비스 URL, 원본 및 받는 사람 속성이 포함됩니다.

Emulator에서 추적 활동을 보려면 다음을 수행합니다.

1. 컴퓨터에서 로컬로 봇을 실행합니다.
2. 에뮬레이터를 사용하여 테스트합니다.
   • 봇과 상호 작용하고 시나리오의 단계를 사용하여 추적 작업을 생성합니다.
   • 봇에서 추적 활동을 내보내면 추적 활동이 Emulator 로그에 표시됩니다.

다음은 봇이 사용하는 QnAMaker 기술 자료 먼저 설정하지 않고 Core 봇을 실행한 경우 확인할 수 있는 추적 작업입니다.

어댑터의 오류 처리기에 추적 작업 추가

어댑터의 켜기 오류 처리기는 턴 중에 봇에서 throw된 기타 catch되지 않은 예외를 catch합니다. 사용자에게 친숙한 메시지를 보내고 예외에 대한 디버깅 정보를 에뮬레이터로 보낼 수 있으므로 오류 처리기는 추적 작업에 적합합니다.

이 예제 코드는 핵심 봇 샘플에서 가져옵니다. 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 처리기는 예외 정보를 포함하는 추적 활동을 만들고 이를 Emulator에 보냅니다.

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를 사용할 수 있습니다. 자세한 내용은 봇에 원격 분석 추가를 참조하세요.
• 각 활동 유형에 대한 자세한 내용은 Bot Framework 활동 스키마를 참조하세요.