Sdílet prostřednictvím

Konfigurace sady Application Insights SDK pomocí ApplicationInsights.config nebo .xml

  • Článek

Sada Application Insights .NET SDK se skládá z mnoha balíčků NuGet. Základní balíček poskytuje rozhraní API pro odesílání telemetrie do Application Insights. Další balíčky poskytují moduly telemetrie a inicializátory pro automatické sledování telemetrie z vaší aplikace a jejího kontextu. Úpravou konfiguračního souboru můžete povolit nebo zakázat moduly telemetrie a inicializátory. Můžete také nastavit parametry pro některé z nich.

Poznámka:

Následující dokumentace spoléhá na klasické rozhraní API Application Insights. Dlouhodobým plánem application Insights je shromažďovat data pomocí OpenTelemetry. Další informace najdete v tématu Povolení OpenTelemetry služby Azure Monitor pro aplikace .NET, Node.js, Python a Java a náš plán OpenTelemetry. Pokyny k migraci jsou k dispozici pro .NET, Node.js a Python.

Konfigurační soubor má název ApplicationInsights.config nebo ApplicationInsights.xml. Název závisí na typu vaší aplikace. Při instalaci většiny verzí sady SDK se do projektu automaticky přidá. Když ve výchozím nastavení použijete automatizované prostředí z projektů šablon sady Visual Studio, které podporují přidání>telemetrie Application Insights, ApplicationInsights.config soubor se vytvoří v kořenové složce projektu. Při kompilaci se zkopíruje do složky přihrádky. Přidá se také do webové aplikace agentem Application Insights na serveru SLUŽBY IIS. Konfigurační soubor se ignoruje, pokud se použije rozšíření pro weby Azure nebo rozšíření pro virtuální počítače Azure a škálovací sady virtuálních počítačů.

Neexistuje ekvivalentní soubor pro řízení sady SDK na webové stránce.

Tento článek popisuje části, které vidíte v konfiguračním souboru, jak řídí komponenty sady SDK a které balíčky NuGet tyto komponenty načítají.

Poznámka:

Pokyny ApplicationInsights.config a .xml se nevztahují na sadu .NET Core SDK. Pokud chcete nakonfigurovat aplikace .NET Core, postupujte podle pokynů v Application Insights pro aplikace ASP.NET Core.

Moduly telemetrie (ASP.NET)

Každý modul telemetrie shromažďuje konkrétní typ dat a k odesílání dat používá základní rozhraní API. Moduly jsou nainstalovány různými balíčky NuGet, které také přidávají požadované řádky do souboru .config.

V konfiguračním souboru pro každý modul je uzel. Pokud chcete modul zakázat, odstraňte uzel nebo ho okomentujte.

Sledování závislosti

Sledování závislostí shromažďuje telemetrická data o voláních vaší aplikace do databází a externích služeb a databází. Pokud chcete povolit, aby tento modul fungoval na serveru SLUŽBY IIS, musíte nainstalovat agenta Application Insights.

Můžete také napsat vlastní kód sledování závislostí pomocí rozhraní TrackDependency API.

Závislosti je možné automaticky kompletovat beze změny kódu pomocí připojení založeného na agentech (bez kódu). Pokud ho chcete použít ve webových aplikacích Azure, povolte rozšíření Application Insights. Pokud ho chcete použít ve virtuálním počítači Azure nebo škálovací sadě virtuálních počítačů Azure, povolte rozšíření Application Monitoring pro virtuální počítače a škálovací sady virtuálních počítačů.

Kolektor výkonu

Kolektor výkonu shromažďuje čítače výkonu systému, jako je procesor, paměť a zatížení sítě z instalací služby IIS. Můžete určit, které čítače se mají shromažďovat, včetně čítačů výkonu, které jste nastavili sami.

Telemetrie diagnostiky Application Insights

Třída DiagnosticsTelemetryModule hlásí chyby v samotném kódu instrumentace Application Insights. Příklady jsou, pokud kód nemá přístup k čítačům výkonu nebo pokud ITelemetryInitializer vyvolá výjimku. Trasování telemetrie sledované tímto modulem se zobrazí v diagnostickém vyhledávání.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Balíček NuGet Microsoft.ApplicationInsights Pokud tento balíček instalujete jenom, soubor ApplicationInsights.config se nevytvořil automaticky.

Vývojářský režim

Třída DeveloperModeWithDebuggerAttachedTelemetryModule vynutí, aby Application Insights TelemetryChannel odesílala data okamžitě, jednu položku telemetrie najednou, když je ladicí program připojený k procesu aplikace. Tento návrh zkracuje dobu mezi okamžikem, kdy vaše aplikace sleduje telemetrii a kdy se zobrazí na portálu Application Insights. Způsobuje významné režijní náklady na využití procesoru a šířky pásma sítě.

Sledování webových požadavků

Sledování webových požadavků hlásí dobu odezvy a kód výsledku požadavků HTTP.

Sledování výjimek

Třída ExceptionTrackingTelemetryModule sleduje neošetřené výjimky ve webové aplikaci. Další informace naleznete v tématu Selhání a výjimky.

Sledování EventSource

Třída EventSourceTelemetryModule umožňuje nakonfigurovat události EventSource, které se mají odesílat do Application Insights jako trasování. Informace o sledování událostí EventSource naleznete v tématu Použití událostí EventSource.

Sledování událostí trasování událostí pro Windows

Tato EtwCollectorTelemetryModule třída umožňuje nakonfigurovat události od poskytovatelů trasování událostí z poskytovatelů trasování událostí pro Windows do Application Insights. Informace o sledování událostí trasování událostí Trasování událostí pro Windows naleznete v tématu Použití událostí pro Windows.

Microsoft.ApplicationInsights

Balíček Microsoft.ApplicationInsights poskytuje základní rozhraní API sady SDK. Ostatní moduly telemetrie používají toto rozhraní API. Můžete ho také použít k definování vlastní telemetrie.

Kanál telemetrie

Kanál telemetrie spravuje ukládání do vyrovnávací paměti a přenos telemetrie do služby Application Insights.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel je výchozí kanál pro webové aplikace. Uloží data do vyrovnávací paměti a využívá mechanismy opakování a úložiště místních disků pro spolehlivější doručování telemetrie.
  • Microsoft.ApplicationInsights.InMemoryChannel je jednoduchý kanál telemetrie. Používá se, pokud není nakonfigurovaný žádný jiný kanál.

Inicializátory telemetrie (ASP.NET)

Inicializátory telemetrie nastavují kontextové vlastnosti, které se odesílají spolu s každou položkou telemetrie.

Můžete napsat vlastní inicializátory pro nastavení kontextových vlastností.

Standardní inicializátory jsou nastaveny buď webovými nebo windowsserverovými balíčky NuGet:

  • AccountIdTelemetryInitializerAccountId nastaví vlastnost.

  • AuthenticatedUserIdTelemetryInitializerAuthenticatedUserId nastaví vlastnost nastavenou sadou JavaScript SDK.

  • AzureRoleEnvironmentTelemetryInitializerRoleName aktualizuje a RoleInstance vlastnosti Device kontextu pro všechny položky telemetrie s informacemi extrahovanými z prostředí modulu runtime Azure.

  • BuildInfoConfigComponentVersionTelemetryInitializerVersion aktualizuje vlastnost Component kontextu pro všechny položky telemetrie s hodnotou extrahovaná ze souboru vytvořeného BuildInfo.config nástrojem MS Build.

  • ClientIpHeaderTelemetryInitializerIp aktualizuje vlastnost Location kontextu všech položek telemetrie na X-Forwarded-For základě hlavičky HTTP požadavku.

  • DeviceTelemetryInitializer aktualizuje následující vlastnosti Device kontextu pro všechny položky telemetrie.

    • Type je nastavena na PChodnotu .
    • Id je nastaven na název domény počítače, na kterém je webová aplikace spuštěná.
    • OemName je nastavena na hodnotu extrahovaná z Win32_ComputerSystem.Manufacturer pole pomocí rozhraní WMI.
    • Model je nastavena na hodnotu extrahovaná z Win32_ComputerSystem.Model pole pomocí rozhraní WMI.
    • NetworkType je nastavena na hodnotu extrahovaná z NetworkInterface vlastnosti.
    • Language je nastaven na název CurrentCulture vlastnosti.

  • DomainNameRoleInstanceTelemetryInitializerRoleInstance aktualizuje vlastnost Device kontextu pro všechny položky telemetrie s názvem domény počítače, na kterém je webová aplikace spuštěná.

  • OperationNameTelemetryInitializerName aktualizuje vlastnost a Name vlastnost RequestTelemetry Operation kontextu všech položek telemetrie na základě metody HTTP a názvy kontroleru ASP.NET MVC a akci vyvolanou ke zpracování požadavku.

  • OperationIdTelemetryInitializer nebo OperationCorrelationTelemetryInitializer aktualizuje Operation.Id kontextovou vlastnost všech položek telemetrie sledovaných při zpracování požadavku s automaticky vygenerovaným RequestTelemetry.Id.

  • SessionTelemetryInitializerId aktualizuje vlastnost Session kontextu pro všechny položky telemetrie s hodnotou extrahovaná ze ai_session souboru cookie vygenerovaného kódem ApplicationInsights instrumentace JavaScript spuštěným v prohlížeči uživatele.

  • SyntheticTelemetryInitializernebo SyntheticUserAgentTelemetryInitializer aktualizuje Uservlastnosti a SessionOperation kontext všech položek telemetrie sledovaných při zpracování požadavku ze syntetického zdroje, jako je test dostupnosti nebo robot vyhledávacího webu. Průzkumník metrik ve výchozím nastavení nezobrazuje syntetickou telemetrii.

    Sada <Filters> identifikující vlastnosti požadavků.

  • UserTelemetryInitializerId aktualizuje a AcquisitionDate vlastnosti User kontextu pro všechny položky telemetrie s hodnotami extrahovanými ze ai_user souboru cookie vygenerovaného kódem instrumentace JavaScriptu Application Insights spuštěným v prohlížeči uživatele.

  • WebTestTelemetryInitializer nastaví ID uživatele, ID relace a syntetické vlastnosti zdroje pro požadavky HTTP, které pocházejí z testů dostupnosti. Sada <Filters> identifikující vlastnosti požadavků.

Pro aplikace .NET spuštěné v Azure Service Fabric můžete zahrnout Microsoft.ApplicationInsights.ServiceFabric balíček NuGet. Tento balíček obsahuje FabricTelemetryInitializer vlastnost, která přidává vlastnosti Service Fabric k položkám telemetrie. Další informace najdete na stránce GitHubu o vlastnostech přidaných tímto balíčkem NuGet.

Procesory telemetrie (ASP.NET)

Procesory telemetrie můžou filtrovat a upravovat jednotlivé položky telemetrie před odesláním ze sady SDK na portál.

Můžete napsat vlastní procesory telemetrie.

Procesor telemetrie adaptivního vzorkování (od verze 2.0.0-beta3)

Tato funkce je ve výchozím nastavení povolená. Pokud vaše aplikace odesílá značnou telemetrii, tento procesor některé z nich odebere.


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

Parametr poskytuje cíl, kterého se algoritmus pokusí dosáhnout. Každá instance sady SDK funguje nezávisle. Takže pokud je váš server clusterem několika počítačů, skutečný objem telemetrie se odpovídajícím způsobem vynásobí.

Přečtěte si další informace o vzorkování.

Procesor telemetrie vzorkování s pevnou rychlostí (z verze 2.0.0-beta1)

K dispozici je také standardní procesor telemetrie vzorkování (od 2.0.1):


    <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

Viz připojovací řetězec ukázky kódu.

InstrumentationKey

Poznámka:

Podpora příjmu dat založeného na instrumentačním klíči skončí 31. března 2025. Příjem klíčů instrumentace bude dál fungovat, ale už nebudeme poskytovat aktualizace ani podporu pro tuto funkci. Přechod na připojovací řetězec, abyste mohli využívat nové funkce.

Toto nastavení určuje prostředek Application Insights, ve kterém se vaše data zobrazují. Obvykle pro každou aplikaci vytvoříte samostatný prostředek se samostatným klíčem.

Pokud chcete klíč nastavit dynamicky, například pokud chcete odesílat výsledky z aplikace do různých prostředků, můžete klíč vynechat z konfiguračního souboru a nastavit ho v kódu.

Pokud chcete nastavit klíč pro všechny instance , včetně standardních TelemetryClientmodulů telemetrie, proveďte tento krok v inicializační metodě, například global.aspx.cs ve službě ASP.NET:

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

Pokud chcete odeslat konkrétní sadu událostí do jiného prostředku, můžete klíč pro konkrétního klienta telemetrie nastavit:


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

Pokud chcete získat nový klíč, vytvořte nový prostředek na portálu Application Insights.

Zprostředkovatel ID aplikace

Poskytovatel je dostupný od verze 2.6.0.

Účelem tohoto poskytovatele je vyhledat ID aplikace na základě instrumentačního klíče. ID aplikace je součástí RequestTelemetry a DependencyTelemetry slouží k určení korelace na portálu.

Tato funkce je dostupná nastavením TelemetryConfiguration.ApplicationIdProvider v kódu nebo v konfiguračním souboru.

Rozhraní: IApplicationIdProvider

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

Poskytujeme dvě implementace v sadě Microsoft.ApplicationInsights SDK: ApplicationInsightsApplicationIdProvider a DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Tento obálka je určená pro rozhraní API profilu. Omezí požadavky a výsledky mezipaměti.

Tento zprostředkovatel se přidá do konfiguračního souboru při instalaci Microsoft.ApplicationInsights.DependencyCollector nebo Microsoft.ApplicationInsights.Web.

Tato třída má volitelnou vlastnost ProfileQueryEndpoint. Ve výchozím nastavení je nastavená na https://dc.services.visualstudio.com/api/profiles/{0}/appIdhodnotu . Pokud potřebujete pro tuto konfiguraci nakonfigurovat proxy server, doporučujeme, abyste zprostředkovali základní adresu a zahrnuli "/api/profiles/{0}/appId". Za {0} běhu na požadavek se nahradí instrumentačním klíčem.

Příklad konfigurace přes ApplicationInsights.config

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

Příklad konfigurace prostřednictvím kódu

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Tento statický zprostředkovatel spoléhá na nakonfigurované páry ID instrumentačního klíče nebo aplikace.

Tato třída má Defined vlastnost, což je Dictionary<string,string> instrumentační klíč nebo dvojice ID aplikace.

Tato třída má volitelnou vlastnost Next, kterou lze použít ke konfiguraci jiného zprostředkovatele, který se má použít při vyžádání instrumentačního klíče, který v konfiguraci neexistuje.

Příklad konfigurace přes ApplicationInsights.config

<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>

Příklad konfigurace prostřednictvím kódu

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

Konfigurace kolekce snímků pro aplikace ASP.NET

Nakonfigurujte kolekci snímků pro ASP.NET aplikace.

Další kroky

Další informace o rozhraní API