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
- Ukázkový kód CoreBot
- Ukázkový kód Application Insights
- Předplatné Microsoft Azure
- Klíč Application Insights
- Znalost Application Insights
- git
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.
Otevřete ukázkovou aplikaci CoreBot v sadě Visual Studio.
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: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.Do metody v
ConfigureServices()
Startup.cs
souboru 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.Požádejte adaptér, aby použil kód middlewaru
ConfigureServices()
, který byl přidán do metody. Provedete to vAdapterWithErrorHandler.cs
parametru TelemetryInitializerMiddleware telemetryInitializerMiddleware v seznamu parametrů konstruktoruUse(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); }
Budete také muset přidat
Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
do seznamu příkazů using vAdapterWithErrorHandler.cs
nástroji .Přidejte do souboru instrumentační klíč
appsettings.json
Application Insights. Souborappsettings.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í souboruappsettings.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:
V
MainDialog.cs
nástroji aktualizujte seznam parametrů konstruktoruIBotTelemetryClient
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 TelemetryLoggerMiddleware
souboru .
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.
Parametr
IBotTelemetryClient telemetryClient
je povinný v konstruktoruFlightBookingRecognizer
vFlightBookingRecognizer.cs
:public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
Dále povolte příkaz
telemetryClient
při vytvářeníLuisRecognizer
v konstruktoruFlightBookingRecognizer
. Uděláte to tak, žetelemetryClient
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
Přejděte na web Azure Portal.
Pokud chcete přejít na stránku Application Insights, vyberte Monitorování, pak Aplikace a najděte ji tam.
Jakmile budete ve službě Application Insights, vyberte Protokoly (Analytics).
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
Tím se vrátí procento dialogových oken vodopádů, které se spustí do dokončení.
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.
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.