Aracılığıyla paylaş

Botunuza telemetri ekleme

  • Makale

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Telemetri günlüğü, bot uygulamalarının Application Insights gibi telemetri hizmetlerine olay verileri göndermesini sağlar. Telemetri en çok hangi özelliklerin kullanıldığını göstererek botunuzla ilgili içgörüler sunar, istenmeyen davranışları algılar ve kullanılabilirlik, performans ve kullanım hakkında görünürlük sağlar.

Bu makalede, Application Insights kullanarak botunuzda telemetrinin nasıl uygulandığı açıklanmaktadır. Bu makalede aşağıdakiler ele alınmaktadır:

  • Botunuzda telemetri verilerini bağlamak ve Application Insights'a bağlanmak için gereken kod.
  • Botunuzun İletişim Kutuları'nda telemetriyi etkinleştirme.
  • Azure AI hizmetleri gibi diğer hizmetlerden kullanım verilerini yakalamak için telemetriyi etkinleştirme.
  • Application Insights'ta telemetri verilerinizi görselleştirme.

Önemli

Telemetride kişisel bilgileri (PII) toplayabilecek bölgesel bir bot için Application Insights kaynağınız ve Azure Bot kaynağınız botla aynı bölgede olmalıdır. Kaynaklar farklı bölgelerdeyse, PII botun coğrafi bölgesinden ayrılabilir.

Önkoşullar

Not

Application Insights örnek kodu CoreBot örnek kodunun üzerine kurulmuştur. Bu makale, telemetri verilerini dahil etmek için CoreBot örnek kodunu değiştirme konusunda size adım adım yol gösterir. Visual Studio'da takip ediyorsanız, işiniz bittiğinde Application Insights örnek koduna sahip olursunuz.

Botunuzda telemetriyi etkinleştirme

Bu makale CoreBot örnek uygulamasından başlar ve telemetriyi herhangi bir botla tümleştirmek için gereken kodu ekler. Bu, Application Insights'ın istekleri izlemeye başlamasını sağlar.

Önemli

Application Insights hesabınızı ayarlamadıysanız ve Application Insights anahtarınızı oluşturduysanız, devam etmeden önce bunu yapın.

  1. Visual Studio'da CoreBot örnek uygulamasını açın.

  2. Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet paketini ekleyin. NuGet kullanma hakkında daha fazla bilgi için bkz . Visual Studio'da paketleri yükleme ve yönetme:

  3. içinde aşağıdaki deyimleri Startup.csekleyin:

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

    İpucu

    CoreBot örnek kodunu güncelleştirerek takip ediyorsanız, için Microsoft.Bot.Builder.Integration.AspNet.Core using deyiminin CoreBot örneğinde zaten var olduğunu fark edeceksiniz.

  4. yöntemine ConfigureServices() Startup.csaşağıdaki kodu ekleyin. Bu, telemetri hizmetlerini bağımlılık ekleme (DI) yoluyla botunuzun kullanımına sunar:

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

    İpucu

    CoreBot örnek kodunu güncelleştirerek takip ediyorsanız zaten mevcut olduğunu services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); fark edeceksiniz.

  5. Bağdaştırıcıya yöntemine eklenen ara yazılım kodunu kullanmasını sağlayın ConfigureServices() . Bunu oluşturucunun AdapterWithErrorHandler.cs parametre listesindeki TelemetryInitializerMiddleware telemetrisiInitializerMiddleware parametresiyle ve Use(telemetryInitializerMiddleware); burada gösterildiği gibi oluşturucudaki deyimiyle yaparsınız:

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

  6. ayrıca içindeki using deyimleri AdapterWithErrorHandler.cslistenize de eklemeniz Microsoft.Bot.Builder.Integration.ApplicationInsights.Core gerekir.

  7. Dosyanıza appsettings.json Application Insights izleme anahtarını ekleyin. Dosya, appsettings.json botunun çalışırken kullandığı dış hizmetlerle ilgili meta verileri içerir. Örneğin Cosmos DB, Application Insights ve Azure AI hizmetleri bağlantısı ve meta veriler burada depolanır. Dosyanıza appsettings.json ekleme şu biçimde olmalıdır:

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

    Not

    Application Insights izleme anahtarını almayla ilgili ayrıntıları Application Insights anahtarları makalesinde bulabilirsiniz.

Bu noktada, Application Insights kullanarak telemetriyi etkinleştirmeye yönelik ön çalışma yapılır. Öykünücü'yü kullanarak botunuzu yerel olarak çalıştırabilir ve ardından Application Insights'a giderek yanıt süresi, genel uygulama durumu ve genel çalışan bilgiler gibi günlüğe kaydedilenleri görebilirsiniz.

Botunuzun iletişim kutusunda telemetriyi etkinleştirme

Herhangi bir ComponentDialog'a yeni bir iletişim kutusu eklerken, üst iletişim kutusunun Microsoft.Bot.Builder.IBotTelemetryClient öğesini devralır. Örneğin, CoreBot örnek uygulamasında tüm iletişim kutuları Bir ComponentDialog olan MainDialog'a eklenir. TelemetryClient özelliğini MainDialog olarak ayarladıktan sonra, buna eklenen tüm iletişim kutuları telemetryClient'ı otomatik olarak ondan devralır, bu nedenle iletişim kutuları eklenirken açıkça ayarlanması gerekmez.

CoreBot örneğinizi güncelleştirmek için aşağıdaki adımları izleyin:

  1. içinde MainDialog.cs, oluşturucunun parametre listesini parametresini içerecek IBotTelemetryClient şekilde güncelleştirin ve aşağıdaki kod parçacığında gösterildiği gibi MainDialog'un TelemetryClient özelliğini bu değere ayarlayın:

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

İpucu

CoreBot örnek kodunu takip edip güncelleştiriyorsanız herhangi bir sorunla karşılaşırsanız Application Insights örnek koduna başvurabilirsiniz.

Telemetri artık bot iletişim kutularınıza eklenir. Botunuzu şimdi çalıştırıyorsanız, Application Insights'ta günlüğe kaydedilen öğeleri görmeniz gerekir; ancak Azure AI hizmeti gibi tümleştirilmiş bir teknolojiniz varsa kodunu da bu koda eklemeniz TelemetryClient gerekir.

Etkinlik olayını ve kişisel bilgi günlüğünü etkinleştirme veya devre dışı bırakma

Etkinlik günlüğünü etkinleştirme veya devre dışı bırakma

Varsayılan olarak, TelemetryInitializerMiddleware botunuz etkinlikleri gönderdiğinde /aldığında telemetriyi günlüğe kaydetmek için öğesini kullanır TelemetryLoggerMiddleware . Etkinlik günlüğü, Application Insights kaynağınızda özel olay günlükleri oluşturur. İsterseniz etkinlik olay günlüğünü Startup.cs kaydederken false TelemetryInitializerMiddleware olarak ayarlayarak logActivityTelemetry devre dışı bırakabilirsiniz.

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

Kişisel bilgi günlüğünü etkinleştirme veya devre dışı bırakma

Varsayılan olarak, etkinlik günlüğü etkinleştirilirse, kullanıcı adı ve etkinlik metni gibi kişisel bilgileri içerme olasılığı yüksek olduğundan, gelen/giden etkinliklerdeki bazı özellikler günlüğe kaydetmeden hariç tutulur. kaydederken TelemetryLoggerMiddlewareStartup.cs olarak aşağıdaki değişikliği yaparak bu özellikleri günlüğe eklemeyi seçebilirsiniz.

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

Ardından, iletişim kutularına telemetri işlevselliği eklemek için nelerin eklenmesi gerektiğini göreceğiz. Bu, hangi iletişim kutularının çalıştırılacağı ve her biri hakkında istatistikler gibi ek bilgiler almanıza olanak tanır.

LUIS ve Soru-Cevap Oluşturma gibi diğer hizmetlerden kullanım verilerini yakalamak için telemetriyi etkinleştirme

Not

Azure Yapay Zeka Soru-Cevap Oluşturma 31 Mart 2025 tarihinde kullanımdan kaldırılacaktır. 1 Ekim 2022 tarihinden itibaren yeni QnA Maker kaynakları veya bilgi bankası makaleleri oluşturamazsınız. Soru ve yanıtlama özelliğinin daha yeni bir sürümü artık Azure AI Dili'nin bir parçası olarak kullanılabilir.

Azure AI Dili'nin bir özelliği olan özel soru yanıtlama, Soru-Cevap Oluşturma hizmetinin güncelleştirilmiş sürümüdür. Bot Framework SDK'sında soru-cevap desteği hakkında daha fazla bilgi için bkz . Doğal dil anlama.

Not

Language Understanding (LUIS) 1 Ekim 2025'te kullanımdan kaldırılacaktır. 1 Nisan 2023'e kadar yeni LUIS kaynakları oluşturamayacaksınız. Dil anlamanın daha yeni bir sürümü artık Azure AI Dili'nin bir parçası olarak kullanılabilir.

Azure AI Dili'nin bir özelliği olan konuşma dili anlama (CLU), LUIS'in güncelleştirilmiş sürümüdür. Bot Framework SDK'sında dil anlama desteği hakkında daha fazla bilgi için bkz . Doğal dil anlama.

Bir sonraki adımda LUIS hizmetinizde telemetri işlevselliğini uygulayacağız. LUIS hizmetinde yerleşik telemetri günlüğü olduğundan LUIS'ten telemetri verilerini almaya başlamak için yapmanız gereken çok az şey vardır. Soru-Cevap Oluşturma özellikli bir botta telemetriyi etkinleştirmek istiyorsanız bkz . Soru-Cevap Oluşturma botunuza telemetri ekleme

  1. IBotTelemetryClient telemetryClient parametresi içindeki oluşturucuda FlightBookingRecognizer FlightBookingRecognizer.csgereklidir:

    public FlightBookingRecognizer(IConfiguration configuration, IBotTelemetryClient telemetryClient)

  2. Ardından oluşturucuda telemetryClient FlightBookingRecognizer öğesini LuisRecognizer oluşturduğunuzda öğesini etkinleştirin. Yeni luisRecognizerOption olarak ekleyerek telemetryClient bunu yapın:

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

İşte bu kadar, telemetri verilerini Application Insights'a kaydeden işlevsel bir bota sahip olmanız gerekir. Botunuzu yerel olarak çalıştırmak için Bot Framework Emulator'ı kullanabilirsiniz. Bot davranışlarında herhangi bir değişiklik görmemeniz gerekir, ancak application insights'ta bilgileri günlüğe kaydeder. Birden çok ileti göndererek botla etkileşime geçin. Sonraki bölümde Application Insights'ta telemetri sonuçlarını gözden geçireceğiz.

Botunuzu test etme ve hata ayıklama hakkında bilgi için aşağıdaki makalelere başvurabilirsiniz:

Application Insights'ta telemetri verilerinizi görselleştirme

Application Insights, bulutta veya şirket içinde barındırılan bot uygulamanızın kullanılabilirliğini, performansını ve kullanımını izler. Azure İzleyici'deki güçlü veri analizi platformunu kullanarak uygulamanızın işlemleri hakkında ayrıntılı içgörüler sağlar ve bir kullanıcının bunları bildirmesini beklemeden hataları tanılar. Application Insights tarafından toplanan telemetri verilerini görmenin birkaç yolu vardır. Birincil yollardan ikisi sorgular ve panodan geçer.

Kusto Sorgularını kullanarak Application Insights'ta telemetri verilerinizi sorgulama

Application Insights'ta günlük sorgularını kullanmayı öğrenmek için bu bölümü başlangıç noktası olarak kullanın. İki yararlı sorgu gösterir ve ek bilgiler içeren diğer belgelere bağlantılar sağlar.

Verilerinizi sorgulamak için

  1. Azure portal'a gidin

  2. Application Insights sayfanıza gitmek için İzleyici'yi ve ardından Uygulamalar'ı seçin ve orada bulun.

  3. Application Insights'ınıza girdikten sonra Günlükler (Analiz) seçeneğini belirleyin.

    Botun Application Insights sayfasında Günlükler (Analiz) düğmesinin yer alacağı ekran görüntüsü.

  4. Bu işlem Sorgu penceresini açar. Aşağıdaki sorguyu girin ve Çalıştır'ı seçin:

    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. Bu, tamamlanmaya kadar çalışan şelale iletişim kutularının yüzdesini döndürür.

    App Insights sorgusunun örnek çıktısı.

İpucu

Günlükler (Analiz) dikey penceresinin sağ üst kısmındaki düğmeyi seçerek herhangi bir sorguyu Application Insights panonuza sabitleyebilirsiniz. Sabitlenmiş olmasını istediğiniz panoyu seçmeniz yeter. Panoyu bir sonraki ziyaret edişinize uygun olacaktır.

Application Insights panosu

Azure'da bir Application Insights kaynağı oluşturduğunuzda otomatik olarak yeni bir pano oluşturulur ve bu kaynakla ilişkilendirilebilir. Application Insights dikey pencerenizin üst kısmındaki Uygulama Panosu etiketli düğmeyi seçerek bu panoyu görebilirsiniz.

Botun Application Insights sayfasında Uygulama Panosu düğmesinin yer alan ekran görüntüsü.

Alternatif olarak, verileri görüntülemek için Azure portalına gidin. Sol taraftaki Pano'yu ve ardından açılan listeden istediğiniz panoyu seçin.

Burada botunuzun performansı ve panonuza sabitlediğiniz ek sorgular hakkında bazı varsayılan bilgiler görürsünüz.

Ek Bilgi