Adicionar atividades de rastreamento ao seu bot

APLICA-SE A: SDK v4

Uma atividade de rastreamento é uma atividade que seu bot pode enviar para o Bot Framework Emulator. Você pode usar atividades de rastreamento para depurar interativamente um bot, pois elas permitem que você visualize informações sobre seu bot enquanto ele é executado localmente.

As atividades de rastreamento são enviadas apenas para o emulador e não para qualquer outro cliente ou canal. O emulador os exibe no log, mas não no painel de bate-papo principal.

• As atividades de rastreamento enviadas por meio do contexto de turno são enviadas por meio dos manipuladores de atividades de envio registrados no contexto de turno.
• As atividades de rastreamento enviadas por meio do contexto de turno são associadas à atividade de entrada, aplicando a referência de conversa, se houver. Para uma mensagem proativa, a resposta ao ID será um novo GUID.
• Independentemente de como é enviada, uma atividade de rastreamento nunca define o sinalizador respondido .

Nota

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser suportados, no entanto, o Java SDK está sendo desativado com suporte final de longo prazo terminando em novembro de 2023.

Os bots existentes construídos com o Java SDK continuarão a funcionar.

Para a criação de novos bots, considere usar o Microsoft Copilot Studio e leia sobre como escolher a solução de copilot certa.

Para obter mais informações, consulte O futuro da criação de bots.

Para usar uma atividade de rastreamento

Para ver uma atividade de rastreamento no emulador, você precisa de um cenário no qual o bot enviará uma atividade de rastreamento, como lançar uma exceção e enviar uma atividade de rastreamento do manipulador de erros de turno do adaptador.

Para enviar uma atividade de rastreamento do seu bot:

1. Crie uma nova atividade.
   • Defina sua propriedade de tipo necessária como "trace".
   • Opcionalmente, defina suas propriedades de nome, rótulo, valor e tipo de valor, conforme apropriado para o rastreamento.
2. Use o método send activity do objeto de contexto turn para enviar a atividade de rastreamento.
   • Esse método adiciona valores para as propriedades necessárias restantes da atividade, com base na atividade de entrada. Essas propriedades incluem a ID do canal, a URL do serviço, de e as propriedades do destinatário.

Para exibir uma atividade de rastreamento no emulador:

1. Execute o bot localmente em sua máquina.
2. Teste-o usando o emulador.
   • Interaja com o bot e use as etapas em seu cenário para gerar a atividade de rastreamento.
   • Quando o bot emite a atividade de rastreamento, a atividade de rastreamento é exibida no log do emulador.

Aqui está uma atividade de rastreamento que você pode ver se executou o bot principal sem primeiro configurar a base de conhecimento do QnAMaker na qual o bot depende.

Adicionar uma atividade de rastreamento ao manipulador de erro no adaptador

O manipulador de erros on turn do adaptador captura qualquer exceção não detetada lançada do bot durante um turno. O manipulador de erros é um bom lugar para uma atividade de rastreamento, pois você pode enviar uma mensagem amigável para o usuário e enviar informações de depuração sobre a exceção para o emulador.

Este código de exemplo é do exemplo de Core Bot . Veja o exemplo completo em C#, JavaScript, Python ou Java.

C#

O manipulador OnTurnError do adaptador cria a atividade de rastreamento para incluir as informações de exceção e as envia para o emulador.

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

O manipulador onTurnError do adaptador cria a atividade de rastreamento para incluir as informações de exceção e as envia para o emulador.

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

No Java SDK, uma AdapterWithErrorHandler classe é incluída como parte do SDK no pacote com.microsoft.bot.integration . O manipulador onTurnError do adaptador cria a atividade de rastreamento para incluir as informações de exceção e as envia para o emulador. O código-fonte do adaptador padrão é mostrado abaixo.

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

O manipulador de on_error do adaptador cria a atividade de rastreamento para incluir as informações de exceção e as envia para o emulador.

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)

Próximos passos

• How to Debug a bot with inspection middleware descreve como adicionar middleware que emite atividades de rastreamento.
• Para depurar um bot implantado, você pode usar o Application Insights. Para obter mais informações, consulte Adicionar telemetria ao bot.
• Para obter informações detalhadas sobre cada tipo de atividade, consulte o esquema de atividade do Bot Framework.