Přidání telemetrie do robota
PLATÍ PRO: SDK v4
Protokolování telemetrie umožňuje aplikacím robotů odesílat data událostí do služeb telemetrie, jako je Application Insights. Telemetrie nabízí přehled o robotovi tím, že ukazuje, které funkce se používají nejvíce, 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 se věnuje následujícím tématům:
- Kód potřebný k připojení telemetrie v robotovi a připojení k Application Insights.
- Jak povolit telemetrii v dialogových oknech robota
- Jak povolit telemetrii zachytávání dat 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ě místního robota, který může shromažďovat identifikovatelné osobní údaje v telemetrii, by váš prostředek Application Insights a prostředek robota Azure měly být ve stejné oblasti jako robot. Pokud jsou prostředky v různých oblastech, může piI opustit geografickou oblast robota.
Požadavky
- Ukázkový kód CoreBotu
- Ukázkový kód Application Insights
- Předplatné Microsoft Azure
- Klíč Application Insights
- Znalost Application Insights
- git
Povolení telemetrie v robotovi
Tento článek začíná z ukázkové aplikace CoreBot a přidá kód potřebný k integraci telemetrie do libovolného robota. Díky tomu může Application Insights začít sledovat požadavky.
Důležité
Pokud jste nenastavili účet Application Insights a vytvořili klíč Application Insights, udělejte to předtím, než budete pokračovat.
Otevřete ukázkovou aplikaci CoreBot v sadě Visual Studio.
Microsoft.Bot.Builder.Integration.ApplicationInsights.Core
Přidejte balíček NuGet. Další informace o používání NuGetu najdete v tématu Instalace a správa balíčků v sadě Visual Studio:Zahrňte následující příkazy do
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 aktualizací ukázkového kódu CoreBotu, všimněte si, že příkaz using pro
Microsoft.Bot.Builder.Integration.AspNet.Core
již existuje v ukázce CoreBotu.Do metody v
ConfigureServices()
Startup.cs
souboru . Tím zpřístupníte telemetrické služby robotovi 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 budete postupovat podle aktualizace ukázkového kódu CoreBotu, všimnete si, že
services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();
už existuje.Dejte adaptéru pokyn, aby používal kód middlewaru, který byl přidán do
ConfigureServices()
metody. Provedete to pomocíAdapterWithErrorHandler.cs
parametru TelemetryInitializerMiddleware telemetryInitializerMiddleware v seznamu parametrů konstruktoru aUse(telemetryInitializerMiddleware);
příkaz v konstruktoru, jak je znázorněno zde: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
souboru .Přidejte do
appsettings.json
souboru instrumentační klíč Application Insights. Souborappsettings.json
obsahuje metadata o externích službách, které robot používá při spuštění. Například připojení a metadata služeb Cosmos DB, Application Insights a Azure AI se tam ukládají. Přidáníappsettings.json
souboru 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 tuto chvíli se provádí 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 zjistit, co se protokoluje, jako je doba odezvy, celkový stav aplikace a obecné informace o spuštění.
Povolení telemetrie v dialogových oknech robota
Při přidávání nového dialogového okna do libovolné komponentyDialog zdědí Microsoft.Bot.Builder.IBotTelemetryClient nadřazeného dialogového okna. Například v ukázkové aplikaci CoreBot se všechny dialogy přidají do MainDialogu, což je ComponentDialog. Jakmile vlastnost TelemetryClient nastavíte na MainDialog, všechna dialogová okna přidaná do něj automaticky dědí telemetriiClient, takže při přidávání dialogů není potřeba explicitně nastavit.
Pokud chcete aktualizovat příklad CoreBotu, postupujte podle následujících kroků:
V
MainDialog.cs
aplikaci aktualizujte seznam parametrů konstruktoru tak, aby zahrnovalIBotTelemetryClient
parametr, a pak nastavte vlastnost TelemetryClient mainDialogu 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 vzorový kód CoreBot a aktualizujete ho , 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 teď robota spustíte, měli byste vidět, že se protokolují věci v Application Insights; Pokud ale máte nějakou integrovanou technologii, jako je služba Azure AI, musíte 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á a přijímá aktivity. Protokolování aktivit vytváří vlastní protokoly událostí v prostředku Application Insights. Pokud chcete, můžete protokolování událostí aktivity zakázat nastavením logActivityTelemetry
na hodnotu false TelemetryInitializerMiddleware
při registraci v Startup.cs.
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é, některé vlastnosti příchozích a odchozích aktivit jsou ve výchozím nastavení vyloučené z protokolování, 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 Startup.cs při registraci TelemetryLoggerMiddleware
.
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é dialogy se spouštějí, a statistiky o každé z nich.
Povolení telemetrie zachytávání dat o využití z jiných služeb, jako jsou LUIS a QnA Maker
Poznámka:
Azure AI QnA Maker bude vyřazený 31. března 2025. Od 1. října 2022 nebudete moci vytvářet nové zdroje ani znalostní báze QnA Maker. Novější verze funkce pro otázky a odpovědi je teď dostupná jako součást jazyka Azure AI.
Vlastní odpověď 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 služby Bot Framework najdete v tématu Principy přirozeného jazyka.
Poznámka:
Služba Language Understanding (LUIS) bude vyřazena 1. října 2025. Od 1. dubna 2023 nebudete moct vytvářet nové prostředky LUIS. Novější verze language understanding je teď dostupná jako součást jazyka Azure AI.
Konverzační jazyk understanding (CLU), funkce jazyka Azure AI, je aktualizovaná verze služby LUIS. Další informace o podpoře porozumění jazyku v sadě SDK služby Bot Framework najdete v tématu Principy přirozeného jazyka.
Dále budeme implementovat funkce telemetrie ve vaší službě LUIS. Služba LUIS má k dispozici integrované protokolování telemetrie, takže pro zahájení získávání telemetrických dat ze služby LUIS je potřeba udělat jen málo. 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 vyžadován v konstruktoruFlightBookingRecognizer
vFlightBookingRecognizer.cs
:public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
Dále povolte
telemetryClient
při vytvářeníLuisRecognizer
v konstruktoruFlightBookingRecognizer
. Uděláte to tak, že přidátetelemetryClient
novou službu 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 znamená, že byste měli 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 . V chování robota byste neměli vidět žádné změny, ale budou se protokolovat informace do Application Insights. Interakce s robotem odesláním více zpráv a v další části zkontrolujeme výsledky telemetrie ve službě 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 v místním prostředí. Využívá výkonnou platformu pro analýzu dat ve službě Azure Monitor, která poskytuje podrobné přehledy o operacích vaší aplikace a diagnostikuje chyby bez čekání na to, aby je uživatel nahlásil. Existuje několik způsobů, jak zobrazit telemetrická data shromážděná službou Application Insights, dva z primárních způsobů jsou prostřednictvím dotazů a řídicího panelu.
Dotazování telemetrických dat v Application Insights pomocí dotazů Kusto
V této části se jako výchozí bod dozvíte, jak používat dotazy protokolu 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 Sledovat, pak Aplikace a vyhledejte ji tam.
Jednou ve službě Application Insights vyberte Protokoly (Analytics).
Tím se otevře 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 vodopádových dialogů, které se spustí k dokončení.
Tip
Libovolný dotaz můžete připnout na řídicí panel Application Insights tak, že v pravém horním rohu okna Protokoly (Analýza) vyberete tlačítko. Stačí vybrat řídicí panel, ke kterému ho chcete připnout, a bude k dispozici při příštím návštěvě daného řídicího panelu.
Řídicí panel Application Insights
Kdykoli v Azure vytvoříte prostředek Application Insights, automaticky se vytvoří a přidružuje nový řídicí panel. Tento řídicí panel můžete zobrazit tak, že vyberete tlačítko v horní části okna Application Insights s popiskem Řídicí panel aplikace.
Pokud chcete zobrazit data, přejděte na web 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.