Tambahkan fitur telemetri ke bot QnA Maker Anda – Layanan Bot

BERLAKU UNTUK: SDK v4

Pencatatan telemetri memungkinkan aplikasi bot mengirim data peristiwa ke layanan telemetri seperti Wawasan Aplikasi. Telemetri menawarkan wawasan tentang bot Anda dengan menunjukkan fitur mana yang paling sering digunakan, mendeteksi perilaku yang tidak diinginkan, dan menawarkan visibilitas ke ketersediaan, kinerja, dan penggunaan.

Itu TelemetryLoggerMiddleware dan QnAMaker kelas di Bot Framework SDK mengaktifkan pencatatan telemetri di bot yang diaktifkan QnA Maker. TelemetryLoggerMiddleware adalah komponen middleware yang mencatat telemetri setiap kali pesan diterima, dikirim, diperbarui, atau dihapus, dan QnAMaker class menyediakan logging kustom yang memperluas kemampuan telemetri.

Dalam artikel ini Anda akan belajar tentang:

• Kode yang diperlukan untuk memasang telemetri di bot Anda
• Kode yang diperlukan untuk mengaktifkan pembuatan log dan laporan QnA Maker siap pakai yang menggunakan properti peristiwa standar.
• Memodifikasi atau memperluas properti peristiwa default SDK untuk mengaktifkan berbagai kebutuhan pelaporan.

Prasyarat

Tambahkan kode telemetri ke bot QnA Maker Anda

Kita akan mulai dengan aplikasi sampel QnA Maker dan menambahkan kode yang diperlukan untuk mengintegrasikan telemetri ke dalam bot yang menggunakan layanan QnA Maker. Ini akan memungkinkan Wawasan Aplikasi untuk melacak permintaan.

1. Buka aplikasi sampel QnA Maker di Visual Studio.

2. Tambahkan Microsoft.Bot.Builder.Integration.ApplicationInsights.Core Paket NuGet. Untuk informasi selengkapnya tentang menggunakan NuGet, lihat Menginstal dan mengelola paket di Visual Studio:

3. Sertakan pernyataan berikut dalam Startup.cs:

   using Microsoft.ApplicationInsights.Extensibility;
   using Microsoft.Bot.Builder.ApplicationInsights;
   using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
   

   Catatan

   Jika Anda mengikuti dengan memperbarui kode sampel QnA Maker, Anda akan melihat bahwa pernyataan penggunaan untuk Microsoft.Bot.Builder.Integration.AspNet.Core sudah ada dalam sampel QnA Maker.

4. Tambahkan kode berikut ke ConfigureServices() metode dalam Startup.cs. Ini membuat layanan telemetri tersedia untuk bot Anda melalui injeksi ketergantungan (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();
   
       // Add the standard telemetry client
       services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>();
   
       // Create the telemetry middleware to track conversation events
       services.AddSingleton<TelemetryLoggerMiddleware>();
   
       // Add the telemetry initializer middleware
       services.AddSingleton<IMiddleware, TelemetryInitializerMiddleware>();
   
       // 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>();
       ...
   
   

   Catatan

   Jika Anda mengikuti dengan memperbarui kode sampel QnA Maker, Anda akan melihat bahwa services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); sudah ada.

5. Instruksikan adaptor untuk menggunakan kode middleware yang ditambahkan ke ConfigureServices() metode. Membuka AdapterWithErrorHandler.cs dan tambahkan IMiddleware middleware ke daftar parameter konstruktor. Tambahkan Use(middleware); pernyataan sebagai baris terakhir dalam konstruktor:

   public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
           : base(credentialProvider)
   
       ...
   
       Use(middleware);
   
   

6. Tambahkan kunci instrumentasi Wawasan Aplikasi di . Anda appsettings.json mengajukan. Itu appsettings.json file berisi metadata tentang layanan eksternal yang digunakan bot saat berjalan, seperti koneksi dan metadata untuk Cosmos DB, Application Insights, dan QnA Maker. Tambahan untuk Anda appsettings.json file harus dalam format ini:

   
       "MicrosoftAppId": "",
       "MicrosoftAppPassword": "",
       "QnAKnowledgebaseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
       "QnAEndpointKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
       "QnAEndpointHostName": "https://xxxxxxxx.azurewebsites.net/qnamaker",
       "ApplicationInsights": 
           "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
       
   
   

Pada titik ini, pekerjaan awal untuk mengaktifkan telemetri menggunakan Wawasan Aplikasi telah selesai. Anda dapat menjalankan bot Anda secara lokal menggunakan Emulator Kerangka Kerja Bot dan kemudian masuk ke Wawasan Aplikasi untuk melihat apa yang dicatat seperti waktu respons, kesehatan aplikasi secara keseluruhan, dan informasi umum yang berjalan.

Selanjutnya kita akan melihat apa yang perlu disertakan untuk menambahkan fungsionalitas telemetri ke layanan QnA Maker.

Aktifkan telemetri untuk mengambil data penggunaan dari layanan QnA Maker

Layanan QnA Maker memiliki pencatatan telemetri bawaan, jadi Anda tidak perlu melakukan banyak hal untuk mulai mendapatkan data telemetri dari QnA Maker. Pertama, kita akan melihat cara menggabungkan telemetri ke dalam kode QnA Maker untuk mengaktifkan logging telemetri bawaan, kemudian kita akan mempelajari cara mengganti atau menambahkan properti ke data peristiwa yang ada untuk memenuhi berbagai kebutuhan pelaporan.

Aktifkan logging QnA Maker default

1. Buat bidang tipe hanya-baca pribadi IBotTelemetryClient di kamu QnABot masuk kelas QnABot.cs:

   public class QnABot : ActivityHandler
       
           private readonly IBotTelemetryClient _telemetryClient;
           ...
   
   

2. Tambahkan sebuah IBotTelemetryClient parameter untuk Anda QnABot konstruktor kelas di QnABot.cs dan tetapkan nilainya ke bidang pribadi yang dibuat pada langkah sebelumnya:

   public QnABot(IConfiguration configuration, ILogger<QnABot> logger, IHttpClientFactory httpClientFactory, IBotTelemetryClient telemetryClient)
   
       ...
       _telemetryClient = telemetryClient;
   
   

3. Itu telemetryClient parameter diperlukan saat membuat instance objek QnAMaker baru di QnABot.cs:

   var qnaMaker = new QnAMaker(new QnAMakerEndpoint
               
                   KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                   EndpointKey = _configuration["QnAEndpointKey"],
                   Host = _configuration["QnAEndpointHostName"]
               ,
               null,
               httpClient,
               _telemetryClient);
   

   Tip

   Pastikan bahwa nama properti yang Anda gunakan di _configuration entri cocok dengan nama properti yang Anda gunakan dalam file AppSettings.json dan nilai untuk properti tersebut diperoleh dengan memilih Lihat Kode pada halaman Basis pengetahuan saya di portal QnA Maker:

   

Lihat data telemetri yang dicatat dari entri default QnA Maker

Anda dapat melihat hasil penggunaan bot QnA Maker Anda di Application Insights setelah menjalankan bot Anda di Bot Framework Emulator dengan melakukan langkah-langkah berikut:

1. Di portal Azure, buka sumber daya Wawasan Aplikasi untuk bot Anda.

2. Dibawah PemantauanPilih Log.

3. Masukkan kueri Kusto berikut, lalu pilih Lari.

   customEvents
   | where name == 'QnaMessage'
   | extend answer = tostring(customDimensions.answer)
   | summarize count() by answer
   

4. Biarkan halaman ini terbuka di browser Anda; kami akan kembali ke sana setelah menambahkan properti kustom baru.

Ubah atau perluas properti acara default

Jika Anda membutuhkan properti yang tidak ditentukan dalam QnAMaker kelas ada dua cara untuk menangani ini, keduanya memerlukan pembuatan kelas Anda sendiri yang berasal dari QnAMaker kelas. Yang pertama dijelaskan di bagian di bawah ini berjudul Menambahkan properti di mana Anda menambahkan properti ke yang sudah ada QnAMessage peristiwa. Metode kedua memungkinkan Anda membuat acara baru yang dapat Anda tambahkan propertinya seperti yang dijelaskan dalam Menambahkan acara baru dengan properti khusus.

Tambahkan properti

Berikut ini menunjukkan bagaimana Anda dapat memperoleh dari QnAMaker kelas. Contoh menunjukkan menambahkan properti “MyImportantProperty” ke QnAMessage peristiwa. Itu QnAMessage peristiwa dicatat setiap kali panggilan QnA GetAnswers dilakukan.

Setelah mempelajari cara menambahkan properti khusus, kita akan belajar cara membuat peristiwa khusus baru dan mengaitkan properti dengannya, lalu kita akan menjalankan bot secara lokal menggunakan Emulator Kerangka Kerja Bot dan melihat apa yang sedang login di Wawasan Aplikasi menggunakan kueri Kusto bahasa.

1. Buat kelas baru bernama MyQnAMaker dalam Microsoft.BotBuilderSamples namespace yang mewarisi dari QnAMaker kelas dan simpan sebagai MyQnAMaker.cs. Untuk mewarisi dari QnAMaker kelas, Anda harus menambahkan Microsoft.Bot.Builder.AI.QnA menggunakan pernyataan. Kode Anda akan muncul sebagai berikut:

   using Microsoft.Bot.Builder.AI.QnA;
   
   namespace Microsoft.BotBuilderSamples
   
       public class MyQnAMaker : QnAMaker
       
   
       
   
   

2. Tambahkan konstruktor kelas ke MyQnAMaker. Perhatikan bahwa Anda memerlukan dua pernyataan penggunaan lagi untuk parameter konstruktor untuk System.Net.Http dan Microsoft.Bot.Builder:

   using Microsoft.Bot.Builder.AI.QnA;
   using System.Net.Http;
   using Microsoft.Bot.Builder;
   
   namespace Microsoft.BotBuilderSamples
   
       public class MyQnAMaker : QnAMaker
       
           public MyQnAMaker(
               QnAMakerEndpoint endpoint,
               QnAMakerOptions options = null,
               HttpClient httpClient = null,
               IBotTelemetryClient telemetryClient = null,
               bool logPersonalInformation = false)
               : base(endpoint, options, httpClient, telemetryClient, logPersonalInformation)
           
   
           
       
   
   

3. Tambahkan properti baru ke acara QnAMessage setelah konstruktor dan sertakan pernyataan System.Collections.Generic, System.Threadingdan System.Threading.Tasks:

   using Microsoft.Bot.Builder.AI.QnA;
   using System.Net.Http;
   using Microsoft.Bot.Builder;
   using System.Collections.Generic;
   using System.Threading;
   using System.Threading.Tasks;
   
   namespace Microsoft.BotBuilderSamples
   
           public class MyQnAMaker : QnAMaker
           
           ...
   
           protected override async Task OnQnaResultsAsync(
                               QueryResult[] queryResults,
                               Microsoft.Bot.Builder.ITurnContext turnContext,
                               Dictionary<string, string> telemetryProperties = null,
                               Dictionary<string, double> telemetryMetrics = null,
                               CancellationToken cancellationToken = default(CancellationToken))
           
               var eventData = await FillQnAEventAsync(
                                       queryResults,
                                       turnContext,
                                       telemetryProperties,
                                       telemetryMetrics,
                                       cancellationToken)
                                   .ConfigureAwait(false);
   
               // Add new property
               eventData.Properties.Add("MyImportantProperty", "myImportantValue");
   
               // Log QnAMessage event
               TelemetryClient.TrackEvent(
                               QnATelemetryConstants.QnaMsgEvent,
                               eventData.Properties,
                               eventData.Metrics
                               );
           
   
       
   
   

4. Ubah bot Anda untuk menggunakan kelas baru, alih-alih membuat QnAMaker objek yang akan Anda buat MyQnAMaker objek di QnABot.cs:

   var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
               
                   KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                   EndpointKey = _configuration["QnAEndpointKey"],
                   Host = _configuration["QnAEndpointHostName"]
               ,
               null,
               httpClient,
               _telemetryClient);
   

Lihat data telemetri yang dicatat dari properti baru PropertiPentingku

Setelah menjalankan bot Anda di Emulator, Anda dapat melihat hasilnya di Wawasan Aplikasi dengan melakukan hal berikut:

1. Beralih kembali ke browser Anda yang memiliki Log (Analitik) tampilan aktif.

2. Masukkan kueri Kusto berikut lalu pilih Lari. Ini akan memberikan hitungan berapa kali properti baru dieksekusi:

   customEvents
   | where name == 'QnaMessage'
   | extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
   | summarize count() by MyImportantProperty
   

3. Untuk menampilkan detail alih-alih hitungan, hapus baris terakhir dan jalankan kembali kueri:

   customEvents
   | where name == 'QnaMessage'
   | extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
   

Tambahkan acara baru dengan properti khusus

Jika Anda perlu mencatat data ke acara yang berbeda dari QnaMessage, Anda dapat membuat acara khusus Anda sendiri dengan propertinya sendiri. Untuk melakukan ini, kami akan menambahkan kode ke akhir MyQnAMaker kelas sebagai berikut:

public class MyQnAMaker : QnAMaker

    ...

    // Create second event.
    var secondEventProperties = new Dictionary<string, string>();

    // Create new property for the second event.
    secondEventProperties.Add(
                        "MyImportantProperty2",
                        "myImportantValue2");

    // Log secondEventProperties event
    TelemetryClient.TrackEvent(
                    "MySecondEvent",
                    secondEventProperties);

Dasbor Wawasan Aplikasi

Setiap kali Anda membuat sumber daya Wawasan Aplikasi di Azure, Azure membuat dasbor baru yang terkait dengan sumber daya Anda. Untuk menampilkan dasbor dari bilah Wawasan Aplikasi, pilih Dasbor Aplikasi.

Atau, untuk melihat data, buka portal Azure, perluas menu portal, lalu pilih Dasbor. Kemudian, pilih dasbor yang Anda inginkan dari menu tarik-turun.

Dasbor menampilkan beberapa informasi default tentang kinerja bot Anda dan kueri lain yang telah Anda sematkan ke dasbor Anda.

informasi tambahan