Application Insights SDK'sını ApplicationInsights.config veya .xml ile yapılandırma

  • Makale
  • Okumak için 7 dakika

Application Insights .NET SDK'sı birçok NuGet paketinden oluşur. Çekirdek paket, Application Insights'a telemetri göndermek için API'yi sağlar. Daha fazla paket , uygulamanızdan ve bağlamından telemetriyi otomatik olarak izlemek için telemetri modülleri ve başlatıcılar sağlar. Yapılandırma dosyasını ayarlayarak telemetri modüllerini ve başlatıcıları etkinleştirebilir veya devre dışı bırakabilirsiniz. Bazıları için de parametre ayarlayabilirsiniz.

Yapılandırma dosyası veya ApplicationInsights.xmlolarak adlandırılırApplicationInsights.config. Ad, uygulamanızın türüne bağlıdır. SDK'nın çoğu sürümünü yüklediğinizde projenize otomatik olarak eklenir. Varsayılan olarak,Application Insights TelemetrisiEkle'yi> destekleyen Visual Studio şablon projelerinden otomatik deneyimi kullandığınızda, ApplicationInsights.config dosya proje kök klasöründe oluşturulur. Derlendiğinde, bin klasörüne kopyalanır. Ayrıca bir IIS sunucusundaki Durum İzleyicisi tarafından bir web uygulamasına eklenir. Azure web siteleri için uzantı veya AzureVM'leri ve sanal makine ölçek kümeleri uzantısı kullanılırsa yapılandırma dosyası yoksayılır.

Bir web sayfasında SDK'yi denetlemek için eşdeğer bir dosya yoktur.

Bu makalede yapılandırma dosyasında gördüğünüz bölümler, BUNLARıN SDK bileşenlerini nasıl denetledikleri ve bu bileşenleri hangi NuGet paketlerinin yüklediği açıklanmaktadır.

Not

ApplicationInsights.config ve .xml yönergeleri .NET Core SDK'sı için geçerli değildir. .NET Core uygulamalarını yapılandırmak için ASP.NET Core uygulamaları için Application Insights'taki yönergeleri izleyin.

Telemetri modülleri (ASP.NET)

Her telemetri modülü belirli bir veri türünü toplar ve verileri göndermek için çekirdek API'yi kullanır. Modüller, .config dosyasına gerekli satırları da ekleyen farklı NuGet paketleri tarafından yüklenir.

Yapılandırma dosyasında her modül için bir düğüm bulunur. Bir modülü devre dışı bırakmak için düğümü silin veya açıklama satırı yapın.

Bağımlılık izleme

Bağımlılık izleme , uygulamanızın veritabanlarına, dış hizmetlere ve veritabanlarına yaptığı çağrılar hakkında telemetri toplar. Bu modülün bir IIS sunucusunda çalışmasına izin vermek için Durum İzleyicisi'ni yüklemeniz gerekir.

TrackDependency API'sini kullanarak kendi bağımlılık izleme kodunuzu da yazabilirsiniz.

Bağımlılıklar, aracı tabanlı (kodsuz) ekleme kullanılarak kodunuzu değiştirmeden otomatik olarak birleştirilebilir. Azure web uygulamalarında kullanmak için Application Insights uzantısını etkinleştirin. Bunu bir Azure VM veya Azure sanal makine ölçek kümesinde kullanmak için VM'ler ve sanal makine ölçek kümeleri için Uygulama İzleme uzantısını etkinleştirin.

Performans toplayıcı

Performans toplayıcıSı, IIS yüklemelerinden CPU, bellek ve ağ yükü gibi sistem performans sayaçlarını toplar. Kendi ayarladığınız performans sayaçları da dahil olmak üzere hangi sayaçların toplandığını belirtebilirsiniz.

Application Insights tanılama telemetrisi

sınıfı, DiagnosticsTelemetryModule Application Insights izleme kodundaki hataları bildirir. Örnek olarak kodun performans sayaçlarına erişip erişemediğini veya ITelemetryInitializer özel durum oluşturabilmesi verilebilir. Bu modül tarafından izlenen izleme telemetrisi Tanılama Aramasında görünür.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Microsoft.ApplicationInsights NuGet paketi. Yalnızca bu paketi yüklerseniz, ApplicationInsights.config dosyası otomatik olarak oluşturulmaz.

Geliştirici modu

sınıfı Application Insights'ı DeveloperModeWithDebuggerAttachedTelemetryModuleTelemetryChannel , bir hata ayıklayıcısı uygulama işlemine eklendiğinde her seferinde bir telemetri öğesi olan verileri hemen göndermeye zorlar. Bu tasarım, uygulamanızın telemetriyi izlediği an ile Application Insights portalında görünmesi arasındaki süreyi azaltır. CPU ve ağ bant genişliği konusunda önemli ek yüke neden olur.

Web isteği izleme

Web isteği izleme, HTTP isteklerinin yanıt süresini ve sonuç kodunu bildirir.

Özel durum izleme

sınıfı web ExceptionTrackingTelemetryModule uygulamanızdaki işlenmeyen özel durumları izler. Daha fazla bilgi için bkz . Hatalar ve özel durumlar.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • Microsoft.ApplicationInsights.Web NuGet paketi.
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: Gözlemlenmeyen görevi izler. Özel durum.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: Çalışan rolleri, Windows hizmetleri ve konsol uygulamaları için işlenmeyen özel durumları izler.
  • Application Insights Windows Server NuGet paketi.

EventSource izleme

sınıfı, EventSourceTelemetryModule EventSource olaylarını Application Insights'a izleme olarak gönderilecek şekilde yapılandırmanıza olanak tanır. EventSource olaylarını izleme hakkında bilgi için bkz. EventSource olaylarını kullanma.

ETW olay izleme

sınıfı, EtwCollectorTelemetryModule ETW sağlayıcılarından gelen olayları izleme olarak Application Insights'a gönderilecek şekilde yapılandırmanıza olanak tanır. ETW olaylarını izleme hakkında bilgi için bkz. ETW olaylarını kullanma.

Microsoft.ApplicationInsights

Paket, Microsoft.ApplicationInsights SDK'nın temel API'sini sağlar. Diğer telemetri modülleri bu API'yi kullanır. Kendi telemetrinizi tanımlamak için de kullanabilirsiniz.

  • ApplicationInsights.config giriş yok.
  • Microsoft.ApplicationInsights NuGet paketi. Yalnızca bu NuGet'i yüklerseniz .config dosyası oluşturulmaz.

Telemetri kanalı

Telemetri kanalı, telemetrinin Application Insights hizmetine arabelleğe alınıp iletilmesini yönetir.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel , web uygulamaları için varsayılan kanaldır. Verileri bellekte arabelleğe alır ve daha güvenilir telemetri teslimi için yeniden deneme mekanizmaları ve yerel disk depolama kullanır.
  • Microsoft.ApplicationInsights.InMemoryChannel basit bir telemetri kanalıdır. Başka bir kanal yapılandırılmamışsa kullanılır.

Telemetri başlatıcıları (ASP.NET)

Telemetri başlatıcıları, her telemetri öğesiyle birlikte gönderilen bağlam özelliklerini ayarlar.

Bağlam özelliklerini ayarlamak için kendi başlatıcılarınızı yazabilirsiniz .

Standart başlatıcıların tümü web veya WindowsServer NuGet paketleri tarafından ayarlanır:

  • AccountIdTelemetryInitializerAccountId özelliğini ayarlar.

  • AuthenticatedUserIdTelemetryInitializerAuthenticatedUserId Özelliği JavaScript SDK'sı tarafından ayarlandığı şekilde ayarlar.

  • AzureRoleEnvironmentTelemetryInitializerRoleName Tüm telemetri öğeleri için bağlamın Device ve RoleInstance özelliklerini Azure çalışma zamanı ortamından ayıklanan bilgilerle güncelleştirir.

  • BuildInfoConfigComponentVersionTelemetryInitializerVersion tüm telemetri öğeleri için bağlamın Component özelliğini MS Build tarafından oluşturulan dosyadan BuildInfo.config ayıklanan değerle güncelleştirir.

  • ClientIpHeaderTelemetryInitializerIp, isteğin Location HTTP üst bilgisine göre tüm telemetri öğelerinin X-Forwarded-For bağlamının özelliğini güncelleştirir.

  • DeviceTelemetryInitializer tüm telemetri öğeleri için bağlamın Device aşağıdaki özelliklerini güncelleştirir.

    • Type olarak ayarlanır PC.
    • Id , web uygulamasının çalıştığı bilgisayarın etki alanı adına ayarlanır.
    • OemName , WMI kullanılarak alandan ayıklanan değere Win32_ComputerSystem.Manufacturer ayarlanır.
    • Model , WMI kullanılarak alandan ayıklanan değere Win32_ComputerSystem.Model ayarlanır.
    • NetworkType özelliğinden ayıklanan değere NetworkInterface ayarlanır.
    • Language özelliğinin CurrentCulture adına ayarlanır.

  • DomainNameRoleInstanceTelemetryInitializerRoleInstance, web uygulamasının Device çalıştığı bilgisayarın etki alanı adıyla tüm telemetri öğeleri için bağlamın özelliğini güncelleştirir.

  • OperationNameTelemetryInitializerNameRequestTelemetry http yöntemini temel alarak tüm telemetri öğelerinin Operation bağlamının ve Name özelliğini ve isteği işlemek için çağrılan ASP.NET MVC denetleyicisinin ve eyleminin adlarını güncelleştirir.

  • OperationIdTelemetryInitializerveya OperationCorrelationTelemetryInitializer otomatik olarak oluşturulan RequestTelemetry.Idile bir isteği işlerken izlenen tüm telemetri öğelerinin bağlam özelliğini güncelleştirirOperation.Id.

  • SessionTelemetryInitializerId, kullanıcının tarayıcısında Session çalışan JavaScript izleme kodu tarafından ApplicationInsights oluşturulan tanımlama bilgisinden ai_session ayıklanan değerle tüm telemetri öğeleri için bağlamın özelliğini güncelleştirir.

  • SyntheticTelemetryInitializerveya SyntheticUserAgentTelemetryInitializer kullanılabilirlik testi veya Operation arama motoru botu gibi yapay bir kaynaktan gelen bir isteği işlerken izlenen tüm telemetri öğelerinin , Sessionve bağlam özelliklerini güncelleştirirUser. Varsayılan olarak ölçüm gezgini yapay telemetri görüntülemez.

    <Filters> İsteklerin özelliklerini tanımlayan küme.

  • UserTelemetryInitializer, kullanıcının tarayıcısında Id çalışan Application Insights JavaScript izleme kodu tarafından oluşturulan tanımlama bilgisinden ai_user ayıklanan değerlerle tüm telemetri öğeleri için bağlamın ve AcquisitionDate özelliklerini User güncelleştirir.

  • WebTestTelemetryInitializerkullanılabilirlik testlerinden gelen HTTP istekleri için kullanıcı kimliğini, oturum kimliğini ve yapay kaynak özelliklerini ayarlar. <Filters> İsteklerin özelliklerini tanımlayan küme.

Azure Service Fabric'te çalışan .NET uygulamaları için NuGet paketini ekleyebilirsiniz Microsoft.ApplicationInsights.ServiceFabric . Bu paket, telemetri öğelerine Service Fabric özellikleri ekleyen bir FabricTelemetryInitializer özellik içerir. Daha fazla bilgi için bu NuGet paketi tarafından eklenen özellikler hakkında GitHub sayfasına bakın.

Telemetri işlemcileri (ASP.NET)

Telemetri işlemcileri, SDK'dan portala gönderilmeden önce her telemetri öğesini filtreleyebilir ve değiştirebilir.

Kendi telemetri işlemcilerinizi yazabilirsiniz.

Uyarlamalı örnekleme telemetri işlemcisi (2.0.0-beta3'ten)

Bu işlev varsayılan olarak etkindir. Uygulamanız önemli miktarda telemetri gönderirse, bu işlemci bazı telemetri verilerini kaldırır.


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

parametresi, algoritmanın gerçekleştirmeye çalıştığı hedefi sağlar. SDK'nın her örneği bağımsız olarak çalışır. Bu nedenle, sunucunuz birkaç makineden oluşan bir kümeyse, gerçek telemetri hacmi buna göre çarpılır.

Örnekleme hakkında daha fazla bilgi edinin.

Sabit hızlı örnekleme telemetri işlemcisi (2.0.0-beta1'den)

Standart bir örnekleme telemetri işlemcisi de vardır (2.0.1'den):


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

Connectionstring

Bkz. bağlantı dizesi kod örnekleri.

InstrumentationKey

Not

31 Mart 2025’te izleme anahtarı alımı desteği sona erecektir. İzleme anahtarı alımı çalışmaya devam edecek, ancak artık özellik için güncelleştirme veya destek sağlamayacağız. Yeni özelliklerden yararlanmak için bağlantı dizelerine geçiş.

Bu ayar, verilerinizin görüntülendiği Application Insights kaynağını belirler. Genellikle, uygulamalarınızın her biri için ayrı bir anahtarla ayrı bir kaynak oluşturursunuz.

Anahtarı dinamik olarak ayarlamak istiyorsanız, örneğin, uygulamanızdan farklı kaynaklara sonuç göndermek istiyorsanız, anahtarı yapılandırma dosyasından atlayabilir ve bunun yerine kodda ayarlayabilirsiniz.

Standart telemetri modülleri de dahil olmak üzere tüm örneklerinin TelemetryClientanahtarını ayarlamak için bu adımı bir ASP.NET hizmetinde global.aspx.cs gibi bir başlatma yönteminde gerçekleştirin:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

Belirli bir olay kümesini farklı bir kaynağa göndermek istiyorsanız, belirli bir telemetri istemcisinin anahtarını ayarlayabilirsiniz:


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

Yeni bir anahtar almak için Application Insights portalında yeni bir kaynak oluşturun.

ApplicationId Sağlayıcısı

Sağlayıcı v2.6.0'dan itibaren kullanılabilir.

Bu sağlayıcının amacı, izleme anahtarına dayalı bir uygulama kimliği aramaktır. Uygulama kimliği ve DependencyTelemetry içinde RequestTelemetry bulunur ve portalda bağıntıyı belirlemek için kullanılır.

Bu işlev, kodda veya yapılandırma dosyasında ayarlanarak TelemetryConfiguration.ApplicationIdProvider kullanılabilir.

Arabirim: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

Microsoft.ApplicationInsights SDK'sında iki uygulama sağlıyoruz: ApplicationInsightsApplicationIdProvider ve DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Bu sarmalayıcı Profil API'mize yöneliktir. İstekleri kısıtlar ve sonuçları önbelleğe alır.

Microsoft.ApplicationInsights.DependencyCollector veya Microsoft.ApplicationInsights.Web yüklediğinizde bu sağlayıcı yapılandırma dosyanıza eklenir.

Bu sınıfın isteğe bağlı bir özelliği ProfileQueryEndpointvardır. Varsayılan olarak olarak ayarlanır https://dc.services.visualstudio.com/api/profiles/{0}/appId. Bu yapılandırma için bir ara sunucu yapılandırmanız gerekiyorsa, temel adresi ara sunucuya eklemenizi ve eklemeniz "/api/profiles/{0}/appId"önerilir. bir {0} , çalışma zamanında istek başına izleme anahtarıyla değiştirilir.

ApplicationInsights.config aracılığıyla örnek yapılandırma

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Kod aracılığıyla örnek yapılandırma

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Bu statik sağlayıcı, yapılandırılmış izleme anahtarı/uygulama kimliği çiftlerinize dayanır.

Bu sınıf, izleme anahtarı/uygulama kimliği çiftlerinin bir Dictionary<string,string> özelliğine sahiptirDefined.

Bu sınıf, yapılandırmanızda mevcut olmayan bir izleme anahtarı istendiğinde kullanmak üzere başka bir sağlayıcı yapılandırmak için kullanılabilen isteğe bağlı özelliğine Nextsahiptir.

ApplicationInsights.config aracılığıyla örnek yapılandırma

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Kod aracılığıyla örnek yapılandırma

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

ASP.NET uygulamalar için anlık görüntü koleksiyonunu yapılandırma

ASP.NET uygulamalar için anlık görüntü koleksiyonu yapılandırma.

Sonraki adımlar

API hakkında daha fazla bilgi edinin