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

  • Článek
  • 8 min ke čtení

Sada Application Přehledy .NET SDK se skládá z mnoha balíčků NuGet. Základní balíček poskytuje rozhraní API pro odesílání telemetrie do Přehledy aplikace. 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 a nastavit pro některé z nich parametry.

Konfigurační soubor je pojmenovaný ApplicationInsights.config nebo ApplicationInsights.xmlv závislosti na typu vaší aplikace. Při instalaci většiny verzí sady SDK se automaticky přidá do projektu. Při použití automatizovaného prostředí z projektů šablon Visual Studio, které podporují přidání > telemetrie aplikace Přehledy telemetrie, se soubor ApplicationInsights.config vytvoří v kořenové složce projektu a při kompilaci se zkopíruje do složky bin. Přidá se také do webové aplikace monitorováním stavu na serveru IIS. Konfigurační soubor se ignoruje, pokud se používá rozšíření webu Neborozšíření Azure pro virtuální počítač Azure a škálovací sada virtuálních počítačů .

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

Tento dokument popisuje oddíly, které vidíte v konfiguračním souboru, jak řídí komponenty sady SDK a které NuGet balíčky načítají.

Poznámka

pokyny ApplicationInsights.config a .xml se nevztahují na sadu .NET Core SDK. Pro konfiguraci aplikací .NET Core postupujte podle tohoto průvodce.

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 .config souboru.

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

Sledování závislostí

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

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

Závislosti je možné automaticky shromažďovat bez úpravy 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í Přehledy aplikace. Pokud ho chcete použít ve škálovací sadě virtuálních počítačů Azure nebo ve škálovací sadě virtuálních počítačů Azure, povolte rozšíření Application Monitoring pro virtuální počítač a škálovací sadu virtuálních počítačů.

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 Přehledy aplikací

Zprávy DiagnosticsTelemetryModule o chybách v samotném kódu instrumentace aplikace Přehledy. Pokud například 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í ve vyhledávání diagnostiky.

* `Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule`
* [Microsoft.ApplicationInsights](https://www.nuget.org/packages/Microsoft.ApplicationInsights) NuGet package. If you only install this package, the ApplicationInsights.config file is not automatically created.

Režim vývojáře

DeveloperModeWithDebuggerAttachedTelemetryModulevynutí, aby aplikace Přehledy TelemetryChannel odesílat 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 aplikace sleduje telemetrii a kdy se zobrazí na portálu Přehledy aplikace. Způsobuje významnou režii při využití procesoru a šířky pásma sítě.

Sledování webových požadavků

Hlásí dobu odezvy a kód výsledku požadavků HTTP.

Sledování výjimek

ExceptionTrackingTelemetryModule sleduje neošetřené výjimky ve webové aplikaci. Podívejte se na chyby a výjimky.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
  • Balíček Microsoft.ApplicationInsights.Web NuGet
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule – sleduje neoobslužné výjimky úkolů.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule– sleduje neošetřené výjimky pro role pracovních procesů, služby Windows a konzolové aplikace.
  • Balíček NuGet serveru Přehledy Windows aplikace.

Sledování služby EventSource

EventSourceTelemetryModuleumožňuje nakonfigurovat události EventSource tak, aby se odesílaly do aplikace Přehledy jako trasování. Informace o sledování událostí EventSource najdete v tématu Použití událostí EventSource.

Sledování událostí etW

EtwCollectorTelemetryModuleumožňuje konfigurovat události od poskytovatelů etW, které se mají odesílat do aplikace Přehledy jako trasování. Informace o sledování událostí ETW najdete v tématu Použití událostí etW.

Microsoft.ApplicationInsights

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

  • V ApplicationInsights.config není žádná položka.
  • Balíček Microsoft.ApplicationInsights NuGet. Pokud jste tento NuGet právě nainstalovali, nevygeneruje se žádný soubor .config.

Kanál telemetrie

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

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel je výchozí kanál webových aplikací. Uloží data do 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, který se používá, 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í vlastností kontextu.

Standardní inicializátory jsou všechny nastavené balíčky Web nebo WindowsServer NuGet:

  • AccountIdTelemetryInitializer nastaví vlastnost AccountId.

  • AuthenticatedUserIdTelemetryInitializer Nastaví vlastnost AuthenticatedUserId nastavenou sadou JavaScript SDK.

  • AzureRoleEnvironmentTelemetryInitializerRoleName aktualizuje kontext 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 BuildInfo.config souboru vytvořeného nástrojem MS Build.

  • ClientIpHeaderTelemetryInitializer aktualizuje Ip 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 nastavená na "PC"
    • 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.
    • Languageje nastaven na název .CurrentCulture

  • 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 RequestTelemetryOperation kontextu všech položek telemetrie na základě metody HTTP a také názvy ASP.NET kontroleru MVC a akce vyvolány pro zpracování požadavku.

  • OperationIdTelemetryInitializernebo OperationCorrelationTelemetryInitializer aktualizuje Operation.Id kontextovou vlastnost všechpoložekch 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 instrumentace ApplicationInsights JavaScript spuštěným v prohlížeči uživatele.

  • SyntheticTelemetryInitializer nebo SyntheticUserAgentTelemetryInitializer aktualizuje Uservlastnosti , Sessiona Operation kontexty všech položek telemetrie sledované při zpracování požadavku ze syntetického zdroje, jako je test dostupnosti nebo robot vyhledávacího stroje. 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 aplikací Přehledy kód instrumentace JavaScript spuštěný 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ů.

U aplikací .NET spuštěných v Service Fabric můžete zahrnout Microsoft.ApplicationInsights.ServiceFabric balíček NuGet. Tento balíček obsahuje vlastnost FabricTelemetryInitializerService Fabric k položkám telemetrie. Další informace najdete na stránce GitHub o vlastnostech přidaných tímto balíčkem NuGet.

Procesory telemetrie (ASP.NET)

Procesory telemetrie můžou filtrovat a upravovat každou položku telemetrie těsně před odesláním ze sady SDK na portál.

Můžete napsat vlastní procesory telemetrie.

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

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


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

Existuje 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

Ukázky kódu připojovacího řetězce

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 této funkce. Přechod na připojovací řetězce , abyste mohli využívat nové funkce.

Toto nastavení určuje prostředek aplikace Přehledy, ve kterém se zobrazí vaše data. Obvykle vytvoříte samostatný prostředek s samostatným klíčem pro každou z vašich aplikací.

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 TelemetryClient, včetně standardních modulů telemetrie. Tento krok proveďte 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 jenom odeslat konkrétní sadu událostí do jiného prostředku, můžete klíč pro konkrétní TelemetryClient 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 Přehledy aplikace.

Zprostředkovatel ID aplikace

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 a slouží k určení korelace na portálu.

Tato funkce je dostupná nastavením TelemetryConfiguration.ApplicationIdProvider v kódu nebo v konfiguraci.

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 poskytovatel 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}/appId. Pokud potřebujete pro tuto konfiguraci nakonfigurovat proxy server, doporučujeme proxy server základní adresu a včetně "/api/profiles//{0}appId". Za{0} běhu se za každou žádost nahradí instrumentačním klíčem.

Příklad konfigurace prostřednictvím 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ý poskytovatel spoléhá na nakonfigurované páry instrumentačního klíče nebo ID aplikace.

Tato třída má vlastnost Defined, což je řetězec slovníku<, řetězec> instrumentačního klíče k párům ID aplikace.

Tato třída má volitelnou vlastnost Next, kterou lze použít ke konfiguraci jiného poskytovatele, který se má použít, když je požadován instrumentační klíč, který neexistuje ve vaší konfiguraci.

Příklad konfigurace prostřednictvím 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

Konfigurace kolekce snímků pro aplikace ASP.NET

Další kroky

Přečtěte si další informace o rozhraní API.