Aracılığıyla paylaş

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

  • Makale

Application Insights .NET SDK'sı birçok NuGet paketinden oluşur. Çekirdek paket, Application Insights'a telemetri göndermek için API 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. Ayrıca bazıları için parametreler de ayarlayabilirsiniz.

Not

Aşağıdaki belgeler Application Insights klasik API'sine dayanır. Application Insights için uzun vadeli plan, OpenTelemetry kullanarak veri toplamaktır. Daha fazla bilgi için bkz . .NET, Node.js, Python ve Java uygulamaları için Azure İzleyici OpenTelemetry'yi etkinleştirme ve OpenTelemetry Yol Haritamız. Geçiş kılavuzu .NET, Node.js ve Python için kullanılabilir.

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 Telemetrisi Ekle'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 Application Insights Aracısı tarafından bir web uygulamasına eklenir. Azure web siteleri için uzantı veya Azure VM'leri ve sanal makine ölçek kümeleri için uzantı 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, SDK bileşenlerini nasıl denetledikleri ve hangi NuGet paketlerinin bu bileşenleri 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. 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 Application Insights Aracısını 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şememe veya ITelemetryInitializer özel durum oluşturması 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'ı DeveloperModeWithDebuggerAttachedTelemetryModule TelemetryChannel uygulama işlemine bir hata ayıklayıcı eklendiğinde verileri hemen, bir kerede bir telemetri öğesi 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ı, ExceptionTrackingTelemetryModule web uygulamanızda 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 Application Insights'a izleme olarak gönderilecek EventSource olaylarını 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 application insights'a izleme olarak gönderilecek olayları 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 dosyasında girdi yok.
  • Microsoft.ApplicationInsights NuGet paketi. Bu NuGet'i yalnızca yüklerseniz hiçbir .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, Azure çalışma zamanı ortamından Device ayıklanan bilgilerle tüm telemetri öğeleri için bağlamın ve RoleInstance özelliklerini 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.

  • OperationNameTelemetryInitializerName RequestTelemetry http yöntemine göre 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 tanımlayıcı özellikleri kümesi.

  • 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 tanımlayıcı özellikleri kümesi.

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 arası)

Bu işlev varsayılan olarak etkindir. Uygulamanız önemli ölçüde 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 ulaşmaya ç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 arası)

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


    <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ı dizesi 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 dahil olmak üzere tüm örneklerinin TelemetryClientanahtarını ayarlamak için, bu adımı 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 içinde RequestTelemetry DependencyTelemetry 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.

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

Bu sınıfın isteğe bağlı bir özelliği ProfileQueryEndpointvardır. Varsayılan olarak 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 sunucu olarak eklemeniz ve eklemeniz "/api/profiles/{0}/appId"önerilir. A {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 bir anlık görüntü koleksiyonu yapılandırın.

Sonraki adımlar

API hakkında daha fazla bilgi edinin