Sdílet prostřednictvím


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

Poznámka:

Vzorový kód Application Insights byl postaven na vzorovém kódu CoreBot. Tento článek vás provede úpravou vzorového kódu CoreBotu tak, aby zahrnoval telemetrii. Pokud sledujete v sadě Visual Studio, budete mít vzorový kód Application Insights do doby, kdy jste hotovi.

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.

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

  2. 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:

  3. 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.

  4. Do metody v ConfigureServices() Startup.cssouboru . 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.

  5. 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 a Use(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);
    }
    
  6. Budete také muset přidat Microsoft.Bot.Builder.Integration.ApplicationInsights.Core do seznamu příkazů using v AdapterWithErrorHandler.cssouboru .

  7. Přidejte do appsettings.json souboru instrumentační klíč Application Insights. Soubor appsettings.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ů:

  1. V MainDialog.csaplikaci aktualizujte seznam parametrů konstruktoru tak, aby zahrnoval IBotTelemetryClient 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.

  1. Parametr IBotTelemetryClient telemetryClient je vyžadován v konstruktoru FlightBookingRecognizer v FlightBookingRecognizer.cs:

    public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
    
  2. Dále povolte telemetryClient při vytváření LuisRecognizer v konstruktoru FlightBookingRecognizer . Uděláte to tak, že přidáte telemetryClient 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

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

  2. Pokud chcete přejít na stránku Application Insights, vyberte Sledovat, pak Aplikace a vyhledejte ji tam.

  3. Jednou ve službě Application Insights vyberte Protokoly (Analytics).

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

  4. 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
    
  5. Tím se vrátí procento vodopádových dialogů, které se spustí k dokončení.

    Ukázkový výstup dotazu App Insights

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.

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

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.

Další informace