Lägga till telemetri till din robot

GÄLLER FÖR: SDK v4

Med telemetriloggning kan robotprogram skicka händelsedata till telemetritjänster som Application Insights. Telemetri ger insikter om din robot genom att visa vilka funktioner som används mest, identifierar oönskat beteende och ger insyn i tillgänglighet, prestanda och användning.

Den här artikeln beskriver hur du implementerar telemetri i din robot med Hjälp av Application Insights. Denna artikel omfattar:

• Den kod som krävs för att koppla upp telemetri i roboten och ansluta till Application Insights.
• Så här aktiverar du telemetri i robotens dialogrutor.
• Så här aktiverar du telemetri för att samla in användningsdata från andra tjänster, till exempel Azure AI-tjänster.
• Visualisera dina telemetridata i Application Insights.

Viktigt!

För en regional robot som kan samla in personligt identifierbar information (PII) i telemetri bör din Application Insights-resurs och din Azure Bot-resurs finnas i samma region som roboten. Om resurserna finns i olika regioner kan PII lämna robotens geografiska region.

Förutsättningar

C#

• CoreBot-exempelkoden
• Application Insights-exempelkoden
• En prenumeration på Microsoft Azure
• En Application Insights-nyckel
• Kunskaper om Application Insights
• git

Kommentar

Application Insights-exempelkoden byggdes ovanpå CoreBot-exempelkoden. Den här artikeln beskriver hur du ändrar CoreBot-exempelkoden så att den innehåller telemetri. Om du följer med i Visual Studio har du Application Insights-exempelkoden när du är klar.

JavaScript

• CoreBot-exempelkoden
• Application Insights-exempelkoden
• En prenumeration på Microsoft Azure
• En Application Insights-nyckel
• Kunskaper om Application Insights
• Visual Studio Code
• Node.js version 10.14 eller senare. Använd kommandot node --version för att fastställa vilken version av noden du har.
• Bot Framework-emulator

Kommentar

Application Insights-exempelkoden byggdes ovanpå CoreBot-exempelkoden. Den här artikeln beskriver hur du ändrar CoreBot-exempelkoden så att den innehåller telemetri. Om du följer med i Visual Studio Code har du Application Insights-exempelkoden när du är klar.

Aktivera telemetri i roboten

C#

Den här artikeln börjar från CoreBot-exempelappen och lägger till den kod som krävs för att integrera telemetri i alla robotar. På så sätt kan Application Insights börja spåra begäranden.

Viktigt!

Om du inte har konfigurerat ditt Application Insights-konto och skapat Application Insights-nyckeln gör du det innan du fortsätter.

1. Öppna CoreBot-exempelappen i Visual Studio.

2. Lägg till NuGet-paketet Microsoft.Bot.Builder.Integration.ApplicationInsights.Core . Mer information om hur du använder NuGet finns i Installera och hantera paket i Visual Studio:

3. Inkludera följande instruktioner i 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;
   

   Dricks

   Om du följer med genom att uppdatera CoreBot-exempelkoden ser du att instruktionen using för Microsoft.Bot.Builder.Integration.AspNet.Core redan finns i CoreBot-exemplet.

4. Inkludera följande kod i ConfigureServices() -metoden i Startup.cs. Detta gör telemetritjänster tillgängliga för din robot via beroendeinmatning (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>();
       ...
   }
   

   Dricks

   Om du följer med genom att uppdatera CoreBot-exempelkoden ser du att den services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); redan finns.

5. Instruera adaptern att använda mellanprogramskoden som lades till i ConfigureServices() metoden. Du gör detta med AdapterWithErrorHandler.cs parametern TelemetryInitializerMiddleware telemetryInitializerMiddleware i konstruktorns parameterlista och -instruktionen Use(telemetryInitializerMiddleware); i konstruktorn enligt följande:

       public AdapterWithErrorHandler(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger, TelemetryInitializerMiddleware telemetryInitializerMiddleware, ConversationState conversationState = null)
           : base(configuration, logger)
   {
       ...
       Use(telemetryInitializerMiddleware);
   }
   

6. Du måste också lägga Microsoft.Bot.Builder.Integration.ApplicationInsights.Core till i din lista över att använda -instruktioner i AdapterWithErrorHandler.cs.

7. Lägg till Application Insights-instrumentationsnyckeln i appsettings.json filen. Filen appsettings.json innehåller metadata om externa tjänster som roboten använder när den körs. Till exempel lagras anslutning och metadata för Cosmos DB, Application Insights och Azure AI-tjänster där. Tillägget till appsettings.json filen måste vara i det här formatet:

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

   Kommentar

   Information om hur du hämtar Application Insights-instrumentationsnyckeln finns i artikeln Application Insights-nycklar.

Nu utförs det preliminära arbetet med att aktivera telemetri med Application Insights. Du kan köra roboten lokalt med emulatorn och sedan gå till Application Insights för att se vad som loggas, till exempel svarstid, övergripande apphälsa och allmän information om körning.

Aktivera telemetri i robotens dialogrutor

När du lägger till en ny dialogruta i valfri ComponentDialog ärver den Microsoft.Bot.Builder.IBotTelemetryClient för den överordnade dialogrutan. I Exempelprogrammet CoreBot läggs till exempel alla dialogrutor till i MainDialog, som är en ComponentDialog. När du har angett egenskapen TelemetryClient till MainDialog ärver alla dialogrutor som läggs till automatiskt telemetriKlienten från den, så den behöver inte anges explicit när du lägger till dialogrutor.

Följ stegen nedan för att uppdatera ditt CoreBot-exempel:

1. I MainDialog.csuppdaterar du konstruktorns parameterlista så att den innehåller parametern IBotTelemetryClient och anger sedan egenskapen TelemetryClient för MainDialog till det värdet enligt följande kodfragment:

   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;
       ...
   }
   

Dricks

Om du följer med och uppdaterar CoreBot-exempelkoden kan du läsa Application Insights-exempelkoden om du stöter på problem.

Telemetri läggs nu till i dina robotdialogrutor. Om du kör roboten nu bör du se att saker loggas i Application Insights. Men om du har någon integrerad teknik, till exempel en Azure AI-tjänst, måste du även lägga till koden i den TelemetryClient koden.

JavaScript

Den här artikeln börjar med CoreBot-exempelappen och lägger till den kod som krävs för att integrera telemetri i alla robotar. På så sätt kan Application Insights börja spåra begäranden.

Viktigt!

Om du inte har konfigurerat ditt Application Insights-konto och skapat Application Insights-nyckeln gör du det innan du fortsätter.

1. Öppna CoreBot-exempelappen i Visual Studio Code.

2. Lägg till Application Insights-nyckeln i .env filen: InstrumentationKey=<EnterInstrumentationKeyHere>. Filen .env innehåller metadata om externa tjänster som roboten använder när den körs. Till exempel lagras Application Insights- och Azure AI-tjänsters anslutning och metadata där. Tillägget till .env filen måste vara i det här formatet:

   MicrosoftAppType=
   MicrosoftAppId=
   MicrosoftAppPassword=
   MicrosoftAppTenantId=
   LuisAppId=
   LuisAPIKey=
   LuisAPIHostName=
   InstrumentationKey=
   

   Kommentar

   Information om hur du hämtar Application Insights-instrumentationsnyckeln finns i artikeln Application Insights-nycklar.

3. Lägg till en referens till modulerna ApplicationInsightsTelemetryClient och TelemetryInitializerMiddleware som finns i botbuilder-applicationinsights Bot Framework SDK. Det gör du genom att lägga till följande kod som börjar längst upp i index.js, strax efter koden för att importera nödvändiga paket:

   const { ApplicationInsightsTelemetryClient, TelemetryInitializerMiddleware } = require('botbuilder-applicationinsights');
   const { TelemetryLoggerMiddleware } = require('botbuilder-core');
   

   Dricks

   JavaScript Bot Samples använder Node.js, som följer CommonJS-modulsystemet, och den inbyggda require funktionen för att inkludera moduler som finns i separata filer.

4. Skapa en ny funktion i slutet av index.js namnet getTelemetryClient som tar instrumentationsnyckeln som en parameter och returnerar en telemetriklient med den ApplicationInsightsTelemetryClient modul som du refererade till tidigare. Den här telemetriklienten är den plats där dina telemetridata skickas till, i det här fallet Application Insights.

   // Listen for Upgrade requests for Streaming.
   server.on('upgrade', async (req, socket, head) => {
       // Create an adapter scoped to this WebSocket connection to allow storing session data.
       const streamingAdapter = new CloudAdapter(botFrameworkAuthentication);
   
       // Set onTurnError for the CloudAdapter created for each connection.
       streamingAdapter.onTurnError = onTurnErrorHandler;
   

5. Därefter måste du lägga till telemetrimellanprogrammet i adapterns mellanprogramspipeline. Det gör du genom att lägga till följande kod som börjar strax efter felhanteringskoden:

   
   // For local development, in-memory storage is used.
   // CAUTION: The Memory Storage used here is for local bot debugging only. When the bot
   // is restarted, anything stored in memory will be gone.
   const memoryStorage = new MemoryStorage();
   

6. För att dialogrutan ska kunna rapportera telemetridata telemetryClient måste den matcha den som används för telemetrimellanprogrammet, det vill dialog.telemetryClient = telemetryClient;

   const server = restify.createServer();
   server.listen(process.env.port || process.env.PORT || 3978, function() {
       console.log(`\n${ server.name } listening to ${ server.url }`);
       console.log('\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator');
       console.log('\nTo talk to your bot, open the emulator select "Open Bot"');
   });
   

7. När du har skapat restify HTTP-webbserverobjektet instruerar du det att använda bodyParser hanteraren.

       }
       return new NullTelemetryClient();
   }
   

   Dricks

   Då används funktionen restifybodyParser. restify är ett "ett Node.js webbtjänstramverk som är optimerat för att skapa semantiskt korrekta RESTful-webbtjänster som är redo för produktionsanvändning i stor skala. restify optimerar för introspektion och prestanda och används i några av de största Node.js distributionerna på jorden." Mer information finns på webbplatsen för restify .

   Node.js följer CommonJS-modulsystemet och använder den inbyggda require funktionen för att inkludera moduler som finns i separata filer.

Nu utförs det preliminära arbetet med att aktivera telemetri med Application Insights. Du kan köra roboten lokalt med emulatorn och sedan gå till Application Insights för att se vad som loggas, till exempel svarstid, övergripande apphälsa och allmän information om körning.

Aktivera eller inaktivera aktivitetshändelse och loggning av personlig information

C#

Aktivera eller inaktivera aktivitetsloggning

Som standard TelemetryInitializerMiddleware använder TelemetryLoggerMiddleware den för att logga telemetri när din robot skickar/tar emot aktiviteter. Aktivitetsloggning skapar anpassade händelseloggar i Application Insights-resursen. Om du vill kan du inaktivera aktivitetshändelseloggning genom att ange logActivityTelemetry false på TelemetryInitializerMiddleware när du registrerar den i 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);
            });
    ...
}

Aktivera eller inaktivera loggning av personlig information

Om aktivitetsloggning är aktiverad utesluts som standard vissa egenskaper för inkommande/utgående aktiviteter från loggning eftersom de sannolikt kommer att innehålla personlig information, till exempel användarnamn och aktivitetstext. Du kan välja att inkludera dessa egenskaper i loggningen genom att göra följande ändring i Startup.cs när du TelemetryLoggerMiddlewareregistrerar .

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);
            });
    ...
}

Nu ska vi se vad som behöver ingå för att lägga till telemetrifunktioner i dialogrutorna. På så sätt kan du få ytterligare information, till exempel vilka dialogrutor som körs och statistik om var och en.

JavaScript

Aktivera eller inaktivera aktivitetsloggning

Som standard TelemetryInitializerMiddleware använder TelemetryLoggerMiddleware den för att logga telemetri när din robot skickar eller tar emot aktiviteter. Aktivitetsloggning skapar anpassade händelseloggar i Application Insights-resursen. Om du vill kan du inaktivera aktivitetshändelseloggning genom att ange logActivityTelemetry false på TelemetryInitializerMiddleware när du registrerar den i index.js.

Följande kodfragment kommer från exempel 21.corebot-app-insightsoch visar anropet till TelemetryInitializerMiddleware:

// For local development, in-memory storage is used.
// CAUTION: The Memory Storage used here is for local bot debugging only. When the bot
// is restarted, anything stored in memory will be gone.
const memoryStorage = new MemoryStorage();

Kodfragmentet nedan visar den ändring som behövs i exemplet 21.corebot-app-insightsi anropet till för att TelemetryInitializerMiddleware inaktivera aktivitetsloggning:

// Add telemetry middleware to the adapter middleware pipeline
var telemetryClient = getTelemetryClient(process.env.InstrumentationKey);
var telemetryLoggerMiddleware = new TelemetryLoggerMiddleware(telemetryClient);
var initializerMiddleware = new TelemetryInitializerMiddleware(telemetryLoggerMiddleware, false);
adapter.use(initializerMiddleware);

Aktivera eller inaktivera loggning av personlig information

När aktivitetsloggning är aktiverad undantas vissa egenskaper för inkommande/utgående aktiviteter från loggning som standard eftersom de sannolikt kommer att innehålla personlig information, till exempel användarnamn och aktivitetstext. Du kan välja att inkludera dessa egenskaper i loggningen genom att ändra parametern logPersonalInformation från false till true när du registrerar TelemetryLoggerMiddleware i index.js.

// For local development, in-memory storage is used.
// CAUTION: The Memory Storage used here is for local bot debugging only. When the bot
// is restarted, anything stored in memory will be gone.
const memoryStorage = new MemoryStorage();

Nu ska vi se vad som behöver ingå för att lägga till telemetrifunktioner i dialogrutorna. På så sätt kan du få ytterligare information, till exempel vilka dialogrutor som körs och statistik om var och en.

Aktivera telemetri för att samla in användningsdata från andra tjänster som LUIS och QnA Maker

Kommentar

Azure AI QnA Maker dras tillbaka den 31 mars 2025. Från och med den 1 oktober 2022 kan du inte skapa nya QnA Maker resurser eller kunskapsbaser för 2022. En nyare version av fråge- och svarsfunktionen är nu tillgänglig som en del av Azure AI Language.

Svar på anpassade frågor, en funktion i Azure AI Language, är den uppdaterade versionen av QnA Maker-tjänsten. Mer information om stöd för frågor och svar i Bot Framework SDK finns i Förstå naturligt språk.

Kommentar

Language Understanding (LUIS) dras tillbaka den 1 oktober 2025. Från och med den 1 april 2023 kan du inte skapa nya LUIS-resurser. En nyare version av språktolkning är nu tillgänglig som en del av Azure AI Language.

Conversational Language Understanding (CLU), en funktion i Azure AI Language, är den uppdaterade versionen av LUIS. Mer information om stöd för språktolkning i Bot Framework SDK finns i Förstå naturligt språk.

C#

Vi implementerar sedan telemetrifunktioner i LUIS-tjänsten. LUIS-tjänsten har inbyggd telemetriloggning tillgänglig så det finns inte mycket du behöver göra för att börja hämta telemetridata från LUIS. Om du är intresserad av att aktivera telemetri i en QnA Maker-aktiverad robot kan du läsa Lägga till telemetri i din QnA Maker-robot

1. Parametern IBotTelemetryClient telemetryClient krävs i FlightBookingRecognizer konstruktorn i FlightBookingRecognizer.cs:

   public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)
   

2. Aktivera telemetryClient sedan när du skapar din LuisRecognizer i FlightBookingRecognizer konstruktorn. Gör detta genom att lägga till telemetryClient som en ny 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);
   }
   

Det är allt, du bör ha en funktionell robot som loggar telemetridata i Application Insights. Du kan använda Bot Framework-emulatorn för att köra roboten lokalt. Du bör inte se några ändringar i robotens beteende, men det kommer att logga in information i Application Insights. Interagera med roboten genom att skicka flera meddelanden och i nästa avsnitt granskar vi telemetriresultaten i Application Insights.

Information om hur du testar och felsöker din robot finns i följande artiklar:

• Felsöka en robot
• Riktlinjer för testning och felsökning
• Felsöka med emulatorn

JavaScript

Vi implementerar sedan telemetrifunktioner i LUIS-tjänsten. LUIS-tjänsten har inbyggd telemetriloggning tillgänglig så det finns inte mycket du behöver göra för att börja hämta telemetridata från LUIS.

Så här aktiverar du telemetriklienten i LUIS-identifieraren:

1. Öppna FlightBookingRecognizer.js

2. Skicka parametern telemetryClient FlightBookingRecognizer till konstruktorn:

   constructor(config, telemetryClient) {
   

3. telemetryClient Ange objektets recognizerOptions fält till egenskapen telemetryClient som skickas till FlightBookingRecognizer konstruktorn. När konstruktorn är klar visas konstruktorn på följande sätt:

   if (luisIsConfigured) {
       // Set the recognizer options depending on which endpoint version you want to use e.g v2 or v3.
       // More details can be found in https://docs.microsoft.com/azure/cognitive-services/luis/luis-migration-api-v3
       const recognizerOptions = {
           apiVersion: 'v3',
           telemetryClient: telemetryClient
       };
   
       this.recognizer = new LuisRecognizer(config, recognizerOptions);
   }
   

4. Och slutligen måste du inkludera telemetryClient när du skapar en instans av FlightBookingRecognizer i index.js:

   const memoryStorage = new MemoryStorage();
   

Det var allt, det var allt. du bör ha en funktionell robot som loggar telemetridata i Application Insights. Du kan använda Bot Framework-emulatorn för att köra roboten lokalt. Du bör inte se några ändringar i robotens beteende, men det kommer att logga in information i Application Insights. Interagera med roboten genom att skicka flera meddelanden, och i nästa avsnitt beskrivs hur du granskar telemetriresultaten i Application Insights.

Information om hur du testar och felsöker din robot finns i följande artiklar:

• Felsöka en robot
• Riktlinjer för testning och felsökning
• Felsöka med emulatorn

Visualisera dina telemetridata i Application Insights

Application Insights övervakar tillgänglighet, prestanda och användning av ditt robotprogram oavsett om det finns i molnet eller lokalt. Den använder den kraftfulla dataanalysplattformen i Azure Monitor för att ge dig djupgående insikter om programmets åtgärder och diagnostisera fel utan att vänta på att en användare ska rapportera dem. Det finns några sätt att se telemetridata som samlas in av Application Insights, två av de primära sätten är genom frågor och instrumentpanelen.

Köra frågor mot dina telemetridata i Application Insights med Kusto-frågor

Använd det här avsnittet som utgångspunkt för att lära dig hur du använder loggfrågor i Application Insights. Den visar två användbara frågor och innehåller länkar till annan dokumentation med ytterligare information.

Så här frågar du dina data

1. Gå till Azure Portal

2. Om du vill gå till sidan Application Insights väljer du Övervaka och sedan Program och hittar den där.

3. När du är i Application Insights väljer du Loggar (Analys).

   

4. Då visas frågefönstret. Ange följande fråga och välj Kör:

   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. Detta returnerar procentandelen vattenfallsdialogrutor som körs till slutförande.

   

Dricks

Du kan fästa valfri fråga på Application Insights-instrumentpanelen genom att välja knappen längst upp till höger på bladet Loggar (analys). Välj bara den instrumentpanel som du vill att den ska fästas på, så blir den tillgänglig nästa gång du besöker instrumentpanelen.

Application Insights-instrumentpanelen

Varje gång du skapar en Application Insights-resurs i Azure skapas och associeras en ny instrumentpanel automatiskt med den. Du kan se instrumentpanelen genom att välja knappen överst på bladet Application Insights med etiketten Programinstrumentpanel.

Du kan också visa data genom att gå till Azure Portal. Välj Instrumentpanel till vänster och välj sedan den instrumentpanel som du vill använda i listrutan.

Där ser du viss standardinformation om robotens prestanda och eventuella ytterligare frågor som du har fäst på instrumentpanelen.

Ytterligare Information

• Lägga till telemetri i din QnA Maker-robot
• Vad är Application Insights?
• Använda Sök i Application Insights
• Skapa anpassade KPI-instrumentpaneler med Azure Application Insights