Ajouter des activités de trace à votre bot

S'APPLIQUE À : SDK v4

Une activité de trace est une activité que votre bot peut envoyer à Bot Framework Emulator. Les activités de trace s’avèrent utiles pour déboguer un bot de manière interactive dans le sens où elles permettent de voir des informations sur votre bot pendant qu’il s’exécute localement.

Les activités de trace sont envoyées uniquement à l’émulateur et non à un autre client ou canal. L’émulateur les affiche dans le journal, mais pas dans le panneau de conversation principal.

• Les activités de trace envoyées via le contexte de tour sont envoyées via les gestionnaires d’activités d’envoi inscrits dans le contexte de tour.
• Les activités de trace envoyées via le contexte de tour sont associées à l’activité entrante, en appliquant la référence de la conversation, s’il en existait une. Pour un message proactif, reply to ID (ID de réponse) est un nouveau GUID.
• Quelle que soit la façon dont elle est envoyée, une activité de trace ne définit jamais l'indicateur répondu.

Remarque

Les kits SDK JavaScript, C# et Python Bot Framework continueront d’être pris en charge. Toutefois, le kit de développement logiciel (SDK) Java est mis hors service avec une prise en charge finale à long terme se terminant en novembre 2023.

Les bots existants créés avec le kit de développement logiciel (SDK) Java continueront de fonctionner.

Pour la nouvelle génération de bots, envisagez d’utiliser Microsoft Copilot Studio et lisez-en plus sur le choix de la solution copilote appropriée.

Pour plus d'informations, consultez Les futures versions de bot.

Pour utiliser une activité de trace

Pour voir une activité de trace dans l’émulateur, vous avez besoin d’un scénario dans lequel votre bot enverra une activité de trace, par exemple en levant une exception et en envoyant une activité de trace à partir du gestionnaire d’erreurs de tour de l’adaptateur.

Pour envoyer une activité de trace à partir de votre bot :

1. Créez une activité.
   • Affectez à sa propriété type la valeur « trace ».
   • Si vous le souhaitez, définissez ses propriétés nom, étiquette, valuer et type valeur en fonction de la trace.
2. Pour envoyer l’activité de trace, utilisez la méthode send activity (activité d’envoi) de l’objet turn context (contexte de tour).
   • Cette méthode ajoute des valeurs pour les autres propriétés nécessaires de l’activité, en fonction de l’activité entrante. Ces propriétés comprennent les propriétés ID de la chaîne, service de l''URL, émetteur et destinataire.

Pour voir une activité de trace dans l’émulateur :

1. Exécutez le bot localement sur votre ordinateur.
2. Testez-le à l’aide de l’émulateur.
   • Interagissez avec le bot et suivez les étapes de votre scénario pour générer l’activité de trace.
   • Quand le bot émet l’activité de trace, celle-ci s’affiche dans le journal de l’émulateur.

Voici une activité de trace qui risque de s'afficher si vous exécutez le bot Core sans configurer au préalable la base de connaissances QnA Maker sur laquelle repose le bot.

Ajouter une activité de trace au gestionnaire d’erreurs de l’adaptateur

Le gestionnaire d’erreurs de tour de l’adaptateur intercepte les exceptions qui ne l’ont pas été et que le bot a levées pendant un tour. Le gestionnaire d'erreur est l'endroit idéal pour une activité de trace, car vous pouvez envoyer un message convivial à l'utilisateur et envoyer des informations de débogage sur l'exception à l'émulateur.

Cet exemple de code est tiré de l’exemple du bot Core. Consultez l'échantillon complet en C#, JavaScript, Python ou Java.

C#

Le gestionnaire OnTurnError de l’adaptateur crée l’activité de trace pour inclure les informations sur les exceptions et les envoie à l’émulateur.

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

Le gestionnaire onTurnError de l’adaptateur crée l’activité de trace pour inclure les informations sur les exceptions et les envoie à l’émulateur.

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

Dans le kit de développement logiciel (SDK) Java, une classe AdapterWithErrorHandler est incluse dans le SDK dans le package com.microsoft.bot.integration. Le gestionnaire onTurnError de l’adaptateur crée l’activité de trace pour inclure les informations sur les exceptions et les envoie à l’émulateur. Le code source de l'adaptateur par défaut est illustré ci-dessous.

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

Le gestionnaire on_error de l’adaptateur crée l’activité de trace pour inclure les informations relatives aux exceptions, avant de les envoyer à l’émulateur.

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)

Étapes suivantes

• Le guide pratique pour Déboguer un bot avec l’intergiciel d’inspection explique comment ajouter l’intergiciel (middleware) qui émet des activités de suivi.
• Pour déboguer un bot déployé, vous pouvez utiliser Application Insights. Pour plus d’informations, consultez Ajouter la télémétrie à votre bot.
• Pour obtenir des informations détaillées sur chaque type d’activité, consultez la rubrique sur le schéma d’activité de Bot Framework.