Lägga till telemetri till din robot

GÄLLER FÖR: SDK v4

Telemetriloggning gör att robotprogram kan 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. Den här artikeln beskriver:

• Den kod som krävs för att koppla telemetri i roboten och ansluta till Application Insights.
• Så här aktiverar du telemetri i chattrobotens 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 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

Anteckning

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

Anteckning

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 din robot

C#

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

Viktigt

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

1. Öppna CoreBot-exempelappen i Visual Studio.

2. Lägg till Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet-paket. 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;
   

   Tips

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

   Tips

   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 listan med användningsuttryck 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 Cosmos DB, Application Insights och Azure AI-tjänstanslutning och metadata där. Tillägget till appsettings.json filen måste vara i följande format:

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

   Anteckning

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

Nu är det preliminära arbetet med att aktivera telemetri med Application Insights klart. Du kan köra din robot 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 som körs.

Aktivera telemetri i chattrobotens 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 uttryckligen när dialogrutor läggs till.

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

1. I MainDialog.csuppdaterar du konstruktorns parameterlista för att inkludera 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;
       ...
   }
   

Tips

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 i koden TelemetryClient .

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 valfri robot. Detta gör att Application Insights kan börja spåra begäranden.

Viktigt

Om du inte har konfigurerat ditt Application Insights-konto och skapat din Application Insights-nyckel 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 följande format:

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

   Anteckning

   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');
   

   Tips

   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, med början 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();
   }
   

   Tips

   Då används funktionen restifybodyParser . restify är 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 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 är det preliminära arbetet med att aktivera telemetri med Application Insights klart. Du kan köra din robot 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 som körs.

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 roboten 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 aktiverat undantas som standard vissa egenskaper för inkommande/utgående aktiviteter från loggning eftersom de sannolikt innehåller 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 roboten 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 aktiverat undantas vissa egenskaper för inkommande/utgående aktiviteter från loggning som standard eftersom de sannolikt innehåller 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

Anteckning

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

Anteckning

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#

Nu ska vi implementera 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 läser du 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 Emulator 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

Nu ska vi implementera 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 telemetryClientFlightBookingRecognizer 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 Emulator 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 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å öppnas 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. Då returneras procentandelen vattenfallsdialogrutor som körs till slutförande.

   

Tips

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 fästa den på, så blir den tillgänglig nästa gång du besöker instrumentpanelen.

Application Insights-instrumentpanelen

När du skapar en Application Insights-resurs i Azure skapas och associeras en ny instrumentpanel automatiskt. 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 visas 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