Přidání telemetrie do robota

PLATÍ PRO: SDK v4

Protokolování telemetrie umožňuje aplikacím robotů odesílat data událostí do telemetrických služeb, jako je Application Insights. Telemetrie nabízí přehled o robotovi tím, že ukazuje, které funkce se používají nejčastěji, detekuje nežádoucí chování a nabízí přehled o dostupnosti, výkonu a využití.

Tento článek popisuje, jak implementovat telemetrii v robotovi pomocí Application Insights. Tento článek popisuje:

  • Kód potřebný k připojení telemetrie robota a připojení k Application Insights.
  • Jak povolit telemetrii v dialogových oknech robota.
  • Jak povolit telemetrii zachytávat data o využití z jiných služeb, jako jsou služby Azure AI.
  • Jak vizualizovat telemetrická data v Application Insights.

Důležité

V případě regionálního robota, který může shromažďovat identifikovatelné osobní údaje (PII) v telemetrii, by se váš prostředek Application Insights a prostředek Azure Bot měly nacházet ve stejné oblasti jako robot. Pokud jsou prostředky v různých oblastech, můžou osobní údaje opustit geografickou oblast robota.

Požadavky

Poznámka

Ukázkový kód Application Insights byl vytvořen na základě ukázkového kódu CoreBot. Tento článek vás provede úpravou ukázkového kódu CoreBot tak, aby zahrnoval telemetrii. Pokud budete v sadě Visual Studio postupovat podle pokynů, budete mít ukázkový kód Application Insights v době, kdy budete hotovi.

Povolení telemetrie v robotovi

Tento článek začíná ukázkovou aplikací CoreBot a přidává kód potřebný k integraci telemetrie do libovolného robota. Tím umožníte Službě Application Insights začít sledovat žádosti.

Důležité

Pokud jste ještě nenastavili účet Application Insights a nevytvořili jste klíč Application Insights, udělejte to, než budete pokračovat.

  1. Otevřete ukázkovou aplikaci CoreBot v sadě Visual Studio.

  2. Přidejte balíček NuGet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core. Další informace o používání NuGetu najdete v tématu Instalace a správa balíčků v sadě Visual Studio:

  3. Do příkazu zahrňte následující příkazy Startup.cs:

    using Microsoft.ApplicationInsights.Extensibility;
    using Microsoft.Bot.Builder.ApplicationInsights;
    using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
    using Microsoft.Bot.Builder.Integration.AspNet.Core;
    

    Tip

    Pokud postupujete podle pokynů aktualizací ukázkového kódu CoreBot, všimněte si, že příkaz using pro Microsoft.Bot.Builder.Integration.AspNet.Core už v ukázce CoreBotu existuje.

  4. Do metody v ConfigureServices()Startup.cssouboru zahrňte následující kód. Tím robotovi zpřístupníte telemetrické služby prostřednictvím injektáže závislostí (DI):

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        ...
            // Create the Bot Framework Adapter with error handling enabled.
            services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();
    
            // Add Application Insights services into service collection
            services.AddApplicationInsightsTelemetry();
    
            // Create the telemetry client.
            services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>();
    
            // Add telemetry initializer that will set the correlation context for all telemetry items.
            services.AddSingleton<ITelemetryInitializer, OperationCorrelationTelemetryInitializer>();
    
            // Add telemetry initializer that sets the user ID and session ID (in addition to other bot-specific properties such as activity ID)
            services.AddSingleton<ITelemetryInitializer, TelemetryBotIdInitializer>();
    
            // Create the telemetry middleware to initialize telemetry gathering
            services.AddSingleton<TelemetryInitializerMiddleware>();
    
            // Create the telemetry middleware (used by the telemetry initializer) to track conversation events
            services.AddSingleton<TelemetryLoggerMiddleware>();
        ...
    }
    

    Tip

    Pokud postupujete podle pokynů aktualizací ukázkového kódu CoreBotu, všimněte si, že services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); už existuje.

  5. Požádejte adaptér, aby použil kód middlewaru ConfigureServices() , který byl přidán do metody. Provedete to v AdapterWithErrorHandler.cs parametru TelemetryInitializerMiddleware telemetryInitializerMiddleware v seznamu parametrů konstruktoru Use(telemetryInitializerMiddleware); a příkazem v konstruktoru, jak je znázorněno tady:

        public AdapterWithErrorHandler(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger, TelemetryInitializerMiddleware telemetryInitializerMiddleware, ConversationState conversationState = null)
            : base(configuration, logger)
    {
        ...
        Use(telemetryInitializerMiddleware);
    }
    
  6. Budete také muset přidat Microsoft.Bot.Builder.Integration.ApplicationInsights.Core do seznamu příkazů using v AdapterWithErrorHandler.csnástroji .

  7. Přidejte do souboru instrumentační klíč appsettings.json Application Insights. Soubor appsettings.json obsahuje metadata o externích službách, které robot používá při spuštění. Ukládají se tam například připojení a metadata služeb Cosmos DB, Application Insights a Azure AI. Přidání souboru appsettings.json musí být v tomto formátu:

    {
        "MicrosoftAppId": "",
        "MicrosoftAppPassword": "",
        "ApplicationInsights": {
            "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }
    }
    

    Poznámka

    Podrobnosti o získání instrumentačního klíče Application Insights najdete v článku Klíče Application Insights.

V tomto okamžiku jsou hotové předběžné práce na povolení telemetrie pomocí Application Insights. Robota můžete spustit místně pomocí emulátoru a pak přejít do Application Insights a podívat se, co se protokoluje, například dobu odezvy, celkový stav aplikace a obecné informace o běhu.

Povolení telemetrie v dialogových oknech robota

Při přidávání nového dialogového okna do libovolného componentDialog zdědí Microsoft.Bot.Builder.IBotTelemetryClient nadřazeného dialogového okna. Například v ukázkové aplikaci CoreBot jsou všechna dialogová okna přidána do MainDialog, což je ComponentDialog. Jakmile nastavíte vlastnost TelemetryClient na MainDialog, všechna dialogová okna přidaná do něj automaticky zdědí telemetriiClient, takže se při přidávání dialogů nemusí explicitně nastavovat.

Postupujte podle následujících kroků a aktualizujte příklad CoreBotu:

  1. V MainDialog.csnástroji aktualizujte seznam parametrů konstruktoru IBotTelemetryClient tak, aby zahrnoval parametr, a pak nastavte vlastnost TelemetryClient mainDialog na danou hodnotu, jak je znázorněno v následujícím fragmentu kódu:

    public MainDialog(IConfiguration configuration, ILogger<MainDialog> logger, IBotTelemetryClient telemetryClient)
        : base(nameof(MainDialog))
    {
        // Set the telemetry client for this and all child dialogs.
        this.TelemetryClient = telemetryClient;
        ...
    }
    

Tip

Pokud sledujete a aktualizujete vzorový kód CoreBotu, můžete se podívat na ukázkový kód Application Insights , pokud narazíte na nějaké problémy.

Telemetrie se teď přidá do dialogových oken robota. Pokud robota spustíte teď, měli byste vidět, že se v Application Insights něco protokoluje. Pokud ale máte nějakou integrovanou technologii, jako je například služba Azure AI, budete muset do tohoto kódu také přidat TelemetryClient .

Povolení nebo zakázání protokolování událostí aktivit a osobních údajů

Povolení nebo zakázání protokolování aktivit

Ve výchozím nastavení se použije TelemetryLoggerMiddleware k protokolování telemetrie, TelemetryInitializerMiddleware když robot odesílá nebo přijímá aktivity. Protokolování aktivit vytvoří ve vašem prostředku Application Insights vlastní protokoly událostí. Pokud chcete, můžete protokolování událostí aktivity zakázat tak, že při registraci v souboru Startup.cs nastavíte logActivityTelemetry hodnotu TelemetryInitializerMiddleware false.

public void ConfigureServices(IServiceCollection services)
{
    ...
    // Add the telemetry initializer middleware
    services.AddSingleton<TelemetryInitializerMiddleware>(sp =>
            {
                var loggerMiddleware = sp.GetService<TelemetryLoggerMiddleware>();
                return new TelemetryInitializerMiddleware(loggerMiddleware, logActivityTelemetry: false);
            });
    ...
}

Povolení nebo zakázání protokolování osobních údajů

Pokud je protokolování aktivit povolené, jsou ve výchozím nastavení některé vlastnosti příchozích a odchozích aktivit z protokolování vyloučeny, protože pravděpodobně obsahují osobní údaje, jako je uživatelské jméno a text aktivity. Tyto vlastnosti můžete zahrnout do protokolování provedením následující změny souboru Startup.cs při registraci TelemetryLoggerMiddlewaresouboru .

public void ConfigureServices(IServiceCollection services)
{
    ...
    // Add the telemetry initializer middleware
    services.AddSingleton<TelemetryLoggerMiddleware>(sp =>
            {
                var telemetryClient = sp.GetService<IBotTelemetryClient>();
                return new TelemetryLoggerMiddleware(telemetryClient, logPersonalInformation: true);
            });
    ...
}

Dále uvidíme, co je potřeba zahrnout, aby se do dialogových oken přidala funkce telemetrie. To vám umožní získat další informace, například jaká dialogová okna se spouští, a statistiky o každém z nich.

Povolení telemetrie zachytávat data o využití z jiných služeb, jako jsou LUIS a QnA Maker

Poznámka

Služba Azure AI QnA Maker bude 31. března 2025 vyřazena. Od 1. října 2022 nebudete moct vytvářet nové prostředky nebo znalostní báze služby QnA Maker. Jako součást jazyka Azure AI je teď k dispozici novější verze funkce pro otázky a odpovědi.

Vlastní odpovídání na otázky, funkce jazyka Azure AI, je aktualizovaná verze služby QnA Maker. Další informace o podpoře otázek a odpovědí v sadě Sdk pro Bot Framework najdete v tématu Principy přirozeného jazyka.

Poznámka

Language Understanding (LUIS) bude vyřazena 1. října 2025. Od 1. dubna 2023 nebudete moct vytvářet nové prostředky SLUŽBY LUIS. Jako součást jazyka Azure AI je teď k dispozici novější verze jazyka Language.

Funkce jazyka Azure AI language understanding (CLU) je aktualizovaná verze služby LUIS. Další informace o podpoře porozumění jazyku v sadě Bot Framework SDK najdete v tématu Principy přirozeného jazyka.

Dále implementujeme telemetrické funkce ve vaší službě LUIS. Služba LUIS má k dispozici integrované protokolování telemetrie, takže je potřeba udělat jen málo, abyste začali získávat telemetrická data ze služby LUIS. Pokud chcete povolit telemetrii v robotovi s podporou služby QnA Maker, přečtěte si téma Přidání telemetrie do robota služby QnA Maker.

  1. Parametr IBotTelemetryClient telemetryClient je povinný v konstruktoru FlightBookingRecognizer v FlightBookingRecognizer.cs:

    public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
    
  2. Dále povolte příkaz telemetryClient při vytváření LuisRecognizer v konstruktoru FlightBookingRecognizer . Uděláte to tak, že telemetryClient přidáte jako novou možnost LuisRecognizerOption:

    if (luisIsConfigured)
    {
        var luisApplication = new LuisApplication(
            configuration["LuisAppId"],
            configuration["LuisAPIKey"],
            "https://" + configuration["LuisAPIHostName"]);
    
        // Set the recognizer options depending on which endpoint version you want to use.
        var recognizerOptions = new LuisRecognizerOptionsV3(luisApplication)
        {
            TelemetryClient = telemetryClient,
        };
        _recognizer = new LuisRecognizer(recognizerOptions);
    }
    

To je ono, měli byste mít funkčního robota, který protokoluje telemetrická data do Application Insights. K místnímu spuštění robota můžete použít Bot Framework Emulator. Neměli byste vidět žádné změny v chování robota, ale budou se zaznamenávat informace do Application Insights. Komunikujte s robotem odesláním několika zpráv a v další části zkontrolujeme výsledky telemetrie v Application Insights.

Informace o testování a ladění robota najdete v následujících článcích:

Vizualizace telemetrických dat v Application Insights

Application Insights monitoruje dostupnost, výkon a využití vaší aplikace robota bez ohledu na to, jestli je hostovaná v cloudu nebo místně. Využívá výkonnou platformu pro analýzu dat ve službě Azure Monitor k tomu, aby vám poskytovala podrobné přehledy o operacích vaší aplikace a diagnostikovala chyby, aniž by čekala, až je uživatel nahlásí. Existuje několik způsobů, jak zobrazit telemetrická data shromážděná službou Application Insights. Dva z hlavních způsobů jsou prostřednictvím dotazů a řídicího panelu.

Dotazování na telemetrická data v Application Insights pomocí dotazů Kusto

Tato část slouží jako výchozí bod, kde se dozvíte, jak používat dotazy na protokoly v Application Insights. Ukazuje dva užitečné dotazy a poskytuje odkazy na další dokumentaci s dalšími informacemi.

Dotazování dat

  1. Přejděte na web Azure Portal.

  2. Pokud chcete přejít na stránku Application Insights, vyberte Monitorování, pak Aplikace a najděte ji tam.

  3. Jakmile budete ve službě Application Insights, vyberte Protokoly (Analytics).

    Snímek obrazovky s tlačítkem Logs (Analytics) na stránce Application Insights robota

  4. Tím se zobrazí okno Dotazu. Zadejte následující dotaz a vyberte Spustit:

    customEvents
    | where name=="WaterfallStart"
    | extend DialogId = customDimensions['DialogId']
    | extend InstanceId = tostring(customDimensions['InstanceId'])
    | join kind=leftouter (customEvents | where name=="WaterfallComplete" | extend InstanceId = tostring(customDimensions['InstanceId'])) on InstanceId
    | summarize starts=countif(name=='WaterfallStart'), completes=countif(name1=='WaterfallComplete') by bin(timestamp, 1d), tostring(DialogId)
    | project Percentage=max_of(0.0, completes * 1.0 / starts), timestamp, tostring(DialogId)
    | render timechart
    
  5. Tím se vrátí procento dialogových oken vodopádů, které se spustí do dokončení.

    Ukázkový výstup dotazu App Insights

Tip

Libovolný dotaz můžete připnout na řídicí panel Application Insights tak, že vyberete tlačítko v pravém horním rohu okna Protokoly (Analýza). Stačí vybrat řídicí panel, na který chcete řídicí panel připnout, a bude k dispozici při příští návštěvě řídicího panelu.

Řídicí panel Application Insights

Kdykoli vytvoříte prostředek Application Insights v Azure, automaticky se vytvoří nový řídicí panel a přidružuje se k němu. Tento řídicí panel můžete zobrazit tak, že vyberete tlačítko v horní části okna Application Insights s popiskem Řídicí panel aplikace.

Snímek obrazovky s tlačítkem Řídicí panel aplikace na stránce Application Insights robota

Případně můžete data zobrazit tak, že přejdete na Azure Portal. Na levé straně vyberte Řídicí panel a v rozevíracím seznamu vyberte požadovaný řídicí panel.

Tam uvidíte některé výchozí informace o výkonu robota a všechny další dotazy, které jste připnuli na řídicí panel.

Další informace