Bagikan melalui

Tambahkan telemetri ke bot Anda

  • Artikel

BERLAKU UNTUK: SDK v4

Pengelogan telemetri memungkinkan aplikasi bot mengirim data peristiwa ke layanan telemetri seperti Application Insights. Telemetri menawarkan wawasan tentang bot Anda dengan menunjukkan fitur mana yang paling banyak digunakan, mendeteksi perilaku yang tidak diinginkan, dan menawarkan visibilitas ke dalam ketersediaan, performa, dan penggunaan.

Artikel ini menjelaskan cara menerapkan telemetri di bot Anda menggunakan Application Insights. Artikel ini membahas:

  • Kode yang diperlukan untuk menghubungkan telemetri di bot Anda dan terhubung ke Application Insights.
  • Cara mengaktifkan telemetri di Dialog bot Anda.
  • Cara mengaktifkan telemetri untuk mengambil data penggunaan dari layanan lain, seperti layanan Azure AI.
  • Cara memvisualisasikan data telemetri Anda di Application Insights.

Penting

Untuk bot regional yang mungkin mengumpulkan informasi pengidentifikasi pribadi (PII) dalam telemetri, sumber daya Application Insights dan sumber daya Azure Bot Anda harus berada di wilayah yang sama dengan bot. Jika sumber daya berada di wilayah yang berbeda, PII mungkin meninggalkan wilayah geografis bot.

Prasyarat

Catatan

Kode sampel Application Insights dibangun di atas kode sampel CoreBot. Artikel ini akan memanah Anda memodifikasi kode sampel CoreBot untuk menggabungkan telemetri. Jika mengikuti di Visual Studio, Anda akan memiliki kode sampel Application Insights pada saat Anda selesai.

Mengaktifkan telemetri di bot Anda

Artikel ini dimulai dari aplikasi sampel CoreBot dan menambahkan kode yang diperlukan untuk mengintegrasikan telemetri ke dalam bot apa pun. Ini akan memungkinkan Application Insights untuk mulai melacak permintaan.

Penting

Jika Anda belum menyiapkan akun Application Insights dan membuat kunci Application Insights, lakukan sebelum melanjutkan.

  1. Buka aplikasi sampel CoreBot di Visual Studio.

  2. Microsoft.Bot.Builder.Integration.ApplicationInsights.Core Tambahkan 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;
using Microsoft.Bot.Builder.Integration.AspNet.Core;

    Tip

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

  4. Sertakan kode berikut dalam ConfigureServices() metode di Startup.cs. Ini akan membuat layanan telemetri tersedia untuk bot Anda melalui injeksi dependensi (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

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

  5. Instruksikan adaptor untuk menggunakan kode middleware yang ditambahkan ke ConfigureServices() metode . Anda melakukan ini AdapterWithErrorHandler.cs dengan parameter TelemetryInitializerMiddleware telemetryInitializerMiddleware dalam daftar parameter konstruktor, dan Use(telemetryInitializerMiddleware); pernyataan dalam konstruktor seperti yang ditunjukkan di sini:

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

  6. Anda juga perlu menambahkan Microsoft.Bot.Builder.Integration.ApplicationInsights.Core ke daftar penggunaan pernyataan di AdapterWithErrorHandler.cs.

  7. Tambahkan kunci instrumentasi Application Insights di file Anda appsettings.json . File appsettings.json berisi metadata tentang layanan eksternal yang digunakan bot saat berjalan. Misalnya, koneksi dan metadata layanan Cosmos DB, Application Insights, dan Azure AI disimpan di sana. Penambahan ke file Anda appsettings.json harus dalam format ini:

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

    Catatan

    Detail tentang mendapatkan kunci instrumentasi Application Insights dapat ditemukan dalam artikel kunci Application Insights.

Pada titik ini, pekerjaan awal untuk mengaktifkan telemetri menggunakan Application Insights selesai. Anda dapat menjalankan bot secara lokal menggunakan Emulator lalu masuk ke Application Insights untuk melihat apa yang sedang dicatat, seperti waktu respons, kesehatan aplikasi secara keseluruhan, dan informasi umum yang berjalan.

Mengaktifkan telemetri dalam dialog bot Anda

Saat menambahkan dialog baru ke ComponentDialog apa pun, dialog tersebut akan mewarisi Microsoft.Bot.Builder.IBotTelemetryClient dari dialog induknya. Misalnya, dalam aplikasi sampel CoreBot, semua dialog ditambahkan ke MainDialog, yang merupakan ComponentDialog. Setelah Anda mengatur properti TelemetryClient ke MainDialog, semua dialog yang ditambahkan ke dalamnya akan secara otomatis mewarisi telemetryClient darinya, sehingga tidak perlu diatur secara eksplisit saat menambahkan dialog.

Ikuti langkah-langkah di bawah ini untuk memperbarui contoh CoreBot Anda:

  1. Di MainDialog.cs, perbarui daftar parameter konstruktor untuk menyertakan IBotTelemetryClient parameter, lalu atur properti TelemetryClient MainDialog ke nilai tersebut seperti yang ditunjukkan dalam cuplikan kode berikut:

    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

Jika Anda mengikuti dan memperbarui kode sampel CoreBot, Anda dapat merujuk ke kode sampel Application Insights jika Mengalami masalah.

Telemetri sekarang ditambahkan ke dialog bot Anda. Jika Anda menjalankan bot sekarang, Anda akan melihat hal-hal yang dicatat di Application Insights; namun, jika Anda memiliki teknologi terintegrasi seperti layanan Azure AI, Anda juga harus menambahkan ke kode tersebut TelemetryClient .

Mengaktifkan atau menonaktifkan peristiwa aktivitas dan pengelogan informasi pribadi

Mengaktifkan atau menonaktifkan pengelogan aktivitas

Secara default, TelemetryInitializerMiddleware akan menggunakan TelemetryLoggerMiddleware untuk mencatat telemetri saat bot Anda mengirim/menerima aktivitas. Pengelogan aktivitas membuat log peristiwa kustom di sumber daya Application Insights Anda. Jika mau, Anda dapat menonaktifkan pengelogan peristiwa aktivitas dengan mengatur logActivityTelemetry ke false saat TelemetryInitializerMiddleware mendaftarkannya di 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);
            });
    ...
}

Mengaktifkan atau menonaktifkan pengelogan informasi pribadi

Secara default, jika pengelogan aktivitas diaktifkan, beberapa properti pada aktivitas masuk/keluar dikecualikan dari pengelogan karena kemungkinan berisi informasi pribadi, seperti nama pengguna dan teks aktivitas. Anda dapat memilih untuk menyertakan properti ini dalam pengelogan Anda dengan membuat perubahan berikut ke Startup.cs saat mendaftarkan 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);
            });
    ...
}

Selanjutnya kita akan melihat apa yang perlu disertakan untuk menambahkan fungsionalitas telemetri ke dialog. Ini akan memungkinkan Anda untuk mendapatkan informasi tambahan seperti dialog apa yang dijalankan, dan statistik tentang masing-masing dialog.

Mengaktifkan telemetri untuk mengambil data penggunaan dari layanan lain seperti LUIS dan QnA Maker

Catatan

Azure AI QnA Maker akan dihentikan pada 31 Maret 2025. Mulai 1 Oktober 2022, Anda tidak akan dapat membuat sumber daya atau pangkalan pengetahuan QnA Maker baru. Versi yang lebih baru dari kemampuan pertanyaan dan jawaban sekarang tersedia sebagai bagian dari Bahasa Azure AI.

Jawaban atas pertanyaan kustom, fitur Bahasa Azure AI, adalah versi terbaru dari layanan QnA Maker. Untuk informasi selengkapnya tentang dukungan tanya jawab di Bot Framework SDK, lihat Pemahaman bahasa alami.

Catatan

Pemahaman Bahasa (LUIS) akan dihentikan pada 1 Oktober 2025. Mulai 1 April 2023, Anda tidak akan dapat membuat sumber daya LUIS baru. Versi pemahaman bahasa yang lebih baru sekarang tersedia sebagai bagian dari Bahasa Azure AI.

Pemahaman bahasa percakapan (CLU), fitur Bahasa Azure AI, adalah versi LUIS yang diperbarui. Untuk informasi selengkapnya tentang dukungan pemahaman bahasa di Bot Framework SDK, lihat Pemahaman bahasa alami.

Kami selanjutnya akan menerapkan fungsionalitas telemetri di layanan LUIS Anda. Layanan LUIS memiliki pengelogan telemetri bawaan yang tersedia sehingga ada sedikit yang perlu Anda lakukan untuk mulai mendapatkan data telemetri dari LUIS. Jika Anda tertarik untuk mengaktifkan telemetri dalam bot yang diaktifkan QnA Maker, lihat Menambahkan telemetri ke bot QnA Maker Anda

  1. Parameter IBotTelemetryClient telemetryClient diperlukan dalam FlightBookingRecognizer konstruktor di FlightBookingRecognizer.cs:

    public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)

  2. Selanjutnya, aktifkan telemetryClient saat Anda membuat LuisRecognizer di FlightBookingRecognizer konstruktor. Lakukan ini dengan menambahkan telemetryClient sebagai LuisRecognizerOption baru:

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

Itu saja, Anda harus memiliki bot fungsional yang mencatat data telemetri ke dalam Application insights. Anda dapat menggunakan Emulator Kerangka Kerja Bot untuk menjalankan bot Anda secara lokal. Anda seharusnya tidak melihat perubahan apa pun dalam perilaku bot, tetapi akan mencatat informasi ke Application Insights. Berinteraksi dengan bot dengan mengirim beberapa pesan dan di bagian berikutnya kami akan meninjau hasil telemetri di Application Insights.

Untuk informasi tentang pengujian dan penelusuran kesalahan bot, Anda bisa merujuk ke artikel berikut:

Memvisualisasikan data telemetri Anda di Application Insights

Application Insights memantau ketersediaan, performa, dan penggunaan aplikasi bot Anda baik yang dihosting di cloud atau lokal. Ini menggunakan platform analisis data yang kuat di Azure Monitor untuk memberi Anda wawasan mendalam tentang operasi aplikasi Anda dan mendiagnosis kesalahan tanpa menunggu pengguna melaporkannya. Ada beberapa cara untuk melihat data telemetri yang dikumpulkan oleh Application Insights, dua cara utamanya adalah melalui kueri dan dasbor.

Mengkueri data telemetri Anda di Application Insights menggunakan Kueri Kusto

Gunakan bagian ini sebagai titik awal untuk mempelajari cara menggunakan kueri log di Application Insights. Ini menunjukkan dua kueri yang berguna dan menyediakan tautan ke dokumentasi lain dengan informasi tambahan.

Untuk mengkueri data Anda

  1. Masuk ke portal Azure

  2. Untuk masuk ke halaman Application Insights Anda, pilih Pantau, lalu Aplikasi, dan temukan di sana.

  3. Setelah berada di Application Insights Anda, pilih Log (Analitik).

    Cuplikan layar dengan tombol Log (Analitik) di halaman Application Insights bot.

  4. Ini akan memunculkan jendela Kueri. Masukkan kueri berikut dan pilih Jalankan:

    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. Ini akan mengembalikan persentase dialog air terjun yang berjalan hingga selesai.

    Sampel output kueri App Insights.

Tip

Anda dapat menyematkan kueri apa pun ke dasbor Application Insights dengan memilih tombol di kanan atas bilah Log (Analitik). Cukup pilih dasbor yang ingin Anda sematkan, dan dasbor tersebut akan tersedia lain kali Anda mengunjungi dasbor tersebut.

Dasbor Application Insights

Setiap kali Anda membuat sumber daya Application Insights di Azure, dasbor baru akan secara otomatis dibuat dan dikaitkan dengannya. Anda dapat melihat dasbor tersebut dengan memilih tombol di bagian atas bilah Application Insights Anda, berlabel Dasbor Aplikasi.

Cuplikan layar dengan tombol Dasbor Aplikasi di halaman Application Insights bot.

Atau, untuk melihat data, buka portal Azure. Pilih Dasbor di sebelah kiri, lalu pilih dasbor yang Anda inginkan dari menu drop-down.

Di sana, Anda akan melihat beberapa informasi default tentang performa bot dan kueri tambahan apa pun yang telah Anda sematkan ke dasbor Anda.

Informasi Tambahan