Traceringsactiviteiten toevoegen aan uw bot

VAN TOEPASSING OP: SDK v4

Een traceringsactiviteit is een activiteit die uw bot naar de Bot Framework Emulator kan verzenden. U kunt traceringsactiviteiten gebruiken om interactief fouten in een bot op te sporen, omdat u hiermee informatie over uw bot kunt bekijken terwijl deze lokaal wordt uitgevoerd.

Traceeractiviteiten worden alleen naar de emulator verzonden en niet naar een andere client of kanaal. De emulator geeft ze weer in het logboek, maar niet in het hoofdchatvenster.

• Traceeractiviteiten die via de turncontext worden verzonden, worden verzonden via de verzendactiviteitshandlers die zijn geregistreerd in de turncontext.
• Traceeractiviteiten die via de turncontext worden verzonden, worden gekoppeld aan de binnenkomende activiteit door de gespreksverwijzing toe te passen, als er een is. Voor een proactief bericht is de antwoord-id een nieuwe GUID.
• Ongeacht hoe deze wordt verzonden, wordt met een traceringsactiviteit nooit de gereageerde vlag ingesteld.

Notitie

De Sdk's voor Bot Framework JavaScript, C# en Python blijven ondersteund, maar de Java SDK wordt buiten gebruik gesteld met definitieve langetermijnondersteuning die eindigt op november 2023.

Bestaande bots die zijn gebouwd met de Java SDK blijven functioneren.

Voor het bouwen van nieuwe bots kunt u Microsoft Copilot Studio gebruiken en lezen over het kiezen van de juiste copilot-oplossing.

Zie De toekomst van botbouw voor meer informatie.

Een traceringsactiviteit gebruiken

Als u een traceringsactiviteit in de emulator wilt zien, hebt u een scenario nodig waarin uw bot een traceringsactiviteit verzendt, zoals het genereren van een uitzondering en het verzenden van een traceringsactiviteit van de adapter bij het inschakelen van fouthandler.

Een traceringsactiviteit verzenden vanuit uw bot:

1. Maak een nieuwe activiteit.
   • Stel de vereiste typeeigenschap in op tracering.
   • U kunt desgewenst de eigenschappen van het type naam, label, waarde en waarde instellen, afhankelijk van de tracering.
2. Gebruik de verzendactiviteitsmethode van het contextobject om de traceringsactiviteit te verzenden.
   • Met deze methode worden waarden toegevoegd voor de resterende vereiste eigenschappen van de activiteit, op basis van de binnenkomende activiteit. Deze eigenschappen omvatten de kanaal-id, service-URL, van en eigenschappen van geadresseerden.

Een traceringsactiviteit weergeven in de emulator:

1. Voer de bot lokaal uit op uw computer.
2. Test deze met behulp van de emulator.
   • Communiceer met de bot en gebruik de stappen in uw scenario om de traceringsactiviteit te genereren.
   • Wanneer uw bot de traceringsactiviteit verzendt, wordt de traceringsactiviteit weergegeven in het emulatorlogboek.

Hier volgt een traceringsactiviteit die u kunt zien als u de Core-bot hebt uitgevoerd zonder eerst de QnAMaker-knowledge base in te stellen waarop de bot afhankelijk is.

Een traceringsactiviteit toevoegen aan de on-error handler van de adapter

De inschakelen fouthandler van de adapter onderschept alle anders ondeugdige uitzonderingen die tijdens een draai van de bot zijn opgetreden. De fouthandler is een goede plek voor een traceringsactiviteit, omdat u een gebruiksvriendelijk bericht naar de gebruiker kunt verzenden en informatie over foutopsporing over de uitzondering naar de emulator kunt verzenden.

Deze voorbeeldcode is afkomstig uit het Core Bot-voorbeeld . Bekijk het volledige voorbeeld in C#, JavaScript, Python of Java.

C#

De OnTurnError-handler van de adapter maakt de traceringsactiviteit om de uitzonderingsgegevens op te nemen en naar de emulator te verzenden.

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

De onTurnError-handler van de adapter maakt de traceringsactiviteit om de uitzonderingsgegevens op te nemen en naar de emulator te verzenden.

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

In de Java SDK wordt een AdapterWithErrorHandler klasse opgenomen als onderdeel van de SDK in het com.microsoft.bot.integration-pakket . De onTurnError-handler van de adapter maakt de traceringsactiviteit om de uitzonderingsgegevens op te nemen en naar de emulator te verzenden. De broncode voor de standaardadapter wordt hieronder weergegeven.

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

De on_error handler van de adapter maakt de traceringsactiviteit om de uitzonderingsgegevens op te nemen en naar de emulator te verzenden.

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)

Volgende stappen

• Fouten opsporen in een bot met inspectie-middleware beschrijft hoe u middleware toevoegt die traceringsactiviteiten verzendt.
• Voor het opsporen van fouten in een geïmplementeerde bot kunt u Application Insights gebruiken. Zie Telemetrie toevoegen aan uw bot voor meer informatie.
• Zie het Bot Framework-activiteitsschema voor gedetailleerde informatie over elk activiteitstype.