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

Článek
11/03/2021
8 min ke čtení

sada Application Insights .net SDK se skládá z řady NuGet balíčků. základní balíček poskytuje rozhraní API pro posí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 a Inicializátory telemetrie a nastavit parametry pro některé z nich.

Konfigurační soubor má název ApplicationInsights.config nebo ApplicationInsights.xml , v závislosti na typu vaší aplikace. Automaticky se přidá do projektu při instalaci většiny verzí sady SDK. ve výchozím nastavení platí, že při použití automatizovaného prostředí z projektů šablon Visual Studio, které podporují přidání > Telemetrie Application Insights, je soubor ApplicationInsights.config vytvořen v kořenové složce projektu a při zkopírování do složky bin. Také se přidá do webové aplikace monitorování stavu na serveru služby IIS. Konfigurační soubor se ignoruje, pokud se použije rozšíření pro web Azure nebo rozšíření pro virtuální počítač Azure a sadu škálování virtuálního počítače .

Pro řízení sady SDK na webové stráncenení k dispozici odpovídající soubor.

tento dokument popisuje oddíly, které vidíte v konfiguračním souboru, jak ovládají součásti sady SDK a které NuGet balíčky tyto součásti načítají.

Poznámka

ApplicationInsights.config a pokyny pro .xml se nevztahují na .NET Core SDK. Pokud chcete konfigurovat aplikace .NET Core, postupujte podle pokynů v tomto průvodci.

Moduly telemetrie (ASP.NET)

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

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

Sledování závislostí

Sledování závislostí shromažďuje telemetrii o voláních, která vaše aplikace vytváří v databázích a externích službách a databázích. Aby mohl tento modul fungovat na serveru služby IIS, je nutné nainstalovat monitorování stavu.

Pomocí rozhraní API TrackDependencymůžete také napsat vlastní kód sledování závislosti.

Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
balíček Microsoft. ApplicationInsights. DependencyCollector NuGet.

Závislosti se dají automaticky shromáždit bez úprav kódu pomocí připojení (bez kódu) na základě agenta. pokud ho chcete použít ve službě Azure web apps, povolte rozšíření Application Insights. Pokud ho chcete použít ve virtuálním počítači Azure nebo Azure Virtual Machine Scale set, povolte rozšíření monitorování aplikací pro virtuální počítače a sadu škálování virtuálního počítače.

Kolektor výkonu

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

Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
balíček Microsoft. ApplicationInsights. PerfCounterCollector NuGet.

Application Insights telemetrie diagnostiky

DiagnosticsTelemetryModulehlásí chyby v samotném kódu instrumentace Application Insights. Například pokud kód nemůže získat přístup k čítačům výkonu nebo ITelemetryInitializer vyvolá výjimku. Sledovací telemetrie sledovanou tímto modulem se zobrazí v diagnostickém vyhledávání.

* `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.

Vývojářský režim

DeveloperModeWithDebuggerAttachedTelemetryModulevynutí, TelemetryChannel aby Application Insights odesílala data okamžitě, jednu položku telemetrie v čase, když je ladicí program připojen k procesu aplikace. tím se zkracuje doba mezi okamžikem, kdy vaše aplikace sleduje telemetrii a když se zobrazuje na portálu Application Insights. Způsobuje značnou režii v CPU a šířce pásma sítě.

Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
balíček NuGet Application Insights Windows serveru

Sledování webových žádostí

Oznamuje dobu odezvy a kód výsledku požadavků HTTP.

Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
balíček Microsoft. ApplicationInsights. Web NuGet

Sledování výjimek

ExceptionTrackingTelemetryModule sleduje neošetřené výjimky ve vaší webové aplikaci. Viz selhání a výjimky.

Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
balíček Microsoft. ApplicationInsights. Web NuGet
Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule -sleduje výjimky nepozorovaných úloh.
Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule-sleduje neošetřené výjimky pro role pracovního procesu, Windows služby a konzolové aplikace.
balíček NuGet Windows serveru Application Insights .

Sledování EventSource

EventSourceTelemetryModuleumožňuje konfigurovat události EventSource k odeslání do Application Insights jako trasování. Další informace o sledování událostí EventSource najdete v tématu použití událostí EventSource.

Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
Microsoft. ApplicationInsights. EventSourceListener

Sledování událostí ETW

EtwCollectorTelemetryModuleumožňuje konfigurovat události od zprostředkovatelů ETW, které se mají odeslat Application Insights jako trasování. Informace o sledování událostí ETW najdete v tématu použití událostí ETW.

Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
Microsoft. ApplicationInsights. EtwCollector

Microsoft. ApplicationInsights

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

V ApplicationInsights.config není žádný záznam.
balíček Microsoft. ApplicationInsights NuGet. pokud tuto NuGet pouze nainstalujete, nebude vygenerován žádný .config soubor.

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ím kanálem pro webové aplikace. Ukládá data do vyrovnávací paměti a využívá mechanismy opakování a úložiště na místním disku pro spolehlivější doručování telemetrie.
Microsoft.ApplicationInsights.InMemoryChannel je odlehčený kanál telemetrie, který se používá, pokud není nakonfigurovaný žádný jiný kanál.

Inicializátory telemetrie (ASP.NET)

Inicializátory telemetrie nastavují vlastnosti kontextu, které se odesílají společně s každou položkou telemetrie.

Můžete napsat vlastní Inicializátory pro nastavení vlastností kontextu.

standardní inicializátory se nastavují buď pomocí webu, nebo balíčků WindowsServer NuGet:

AccountIdTelemetryInitializer nastaví vlastnost AccountId.
AuthenticatedUserIdTelemetryInitializer nastaví vlastnost AuthenticatedUserId dle sady JavaScript SDK.
AzureRoleEnvironmentTelemetryInitializer aktualizuje RoleName vlastnosti a RoleInstance Device kontextu pro všechny položky telemetrie s informacemi získanými z běhového prostředí Azure.
BuildInfoConfigComponentVersionTelemetryInitializer aktualizuje Version vlastnost Component Context pro všechny položky telemetrie s hodnotou extrahovanou ze BuildInfo.config souboru vytvořeného pomocí sestavení MS Build.
ClientIpHeaderTelemetryInitializer aktualizuje Ip vlastnost Location kontextu všech položek telemetrie na základě X-Forwarded-For hlavičky HTTP žádosti.
DeviceTelemetryInitializer aktualizuje následující vlastnosti Device kontextu pro všechny položky telemetrie.
- Type je nastavená na "počítač"
- Id je nastaven na název domény počítače, na kterém je webová aplikace spuštěna.
- OemName hodnota je nastavená na extrakci hodnoty z Win32_ComputerSystem.Manufacturer pole pomocí rozhraní WMI.
- Model hodnota je nastavená na extrakci hodnoty z Win32_ComputerSystem.Model pole pomocí rozhraní WMI.
- NetworkType je nastaven na hodnotu extrahovanou z NetworkInterface .
- Language je nastaven na název CurrentCulture .
DomainNameRoleInstanceTelemetryInitializer aktualizuje RoleInstance vlastnost Device Context pro všechny položky telemetrie s názvem domény počítače, na kterém je webová aplikace spuštěná.
OperationNameTelemetryInitializeraktualizuje Name vlastnost RequestTelemetry a Name vlastnosti Operation kontextu všech položek telemetrie na základě metody HTTP a také názvů ASP.NET kontroler MVC a akce vyvolané ke zpracování žádosti.
OperationIdTelemetryInitializer nebo OperationCorrelationTelemetryInitializer aktualizuje Operation.Id vlastnost Context všech položek telemetrie, které jsou sledovány při zpracování žádosti s automaticky vygenerovaným objektem RequestTelemetry.Id .
SessionTelemetryInitializer aktualizuje Id vlastnost Session Context pro všechny položky telemetrie s hodnotou extrahovanou ze ai_session souboru cookie generovaného kódem instrumentace ApplicationInsights JavaScript spuštěným v prohlížeči uživatele.
SyntheticTelemetryInitializer nebo SyntheticUserAgentTelemetryInitializer aktualizuje User vlastnosti, Session a Operation kontexty všech položek telemetrie, které jsou sledovány při zpracování žádosti z syntetického zdroje, jako je například test dostupnosti nebo robot vyhledávače. Ve výchozím nastavení Průzkumník metrik nezobrazuje syntetickou telemetrii.

<Filters>Sada identifikující vlastnosti požadavků.
UserTelemetryInitializeraktualizuje Id vlastnosti a AcquisitionDate User pro kontext pro všechny položky telemetrie s hodnotami extrahované ze ai_user souboru cookie generovaného kódem Application Insights JavaScript instrumentace 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. <Filters>Sada identifikující vlastnosti požadavků.

pro aplikace .net běžící v Service Fabric můžete zahrnout Microsoft.ApplicationInsights.ServiceFabric balíček NuGet. tento balíček zahrnuje FabricTelemetryInitializer , který přidává vlastnosti Service Fabric do položek telemetrie. další informace najdete na stránce GitHub o vlastnostech přidaných tímto NuGet balíčku.

Procesory telemetrie (ASP.NET)

Procesory telemetrie mohou 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 2.0.0-beta3)

Tato možnost je ve výchozím nastavení zapnutá. Pokud vaše aplikace odesílá velké množství telemetrie, tento procesor některé z těchto dat odebere.


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

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

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

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

K dispozici je také standardní vzorkovací procesor telemetrie (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>

Instrumentační klíč

Tím se určí prostředek Přehledy, ve kterém se vaše data zobrazí. Obvykle vytvoříte samostatný prostředek s odděleným klíčem pro každou aplikaci.

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

Nastavení klíče pro všechny instance TelemetryClient, včetně standardních modulů telemetrie Proveďte to v inicializační metodě, například global.aspx.cs v ASP.NET službě:

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 nastavit klíč pro konkrétní telemetriiClient:


    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 Přehledy Portal.

Zprostředkovatel ApplicationId

Dostupné od v2.6.0

Účelem tohoto zprostředkovatele je vyhledat ID aplikace založené na instrumentačním klíči. ID aplikace je součástí RequestTelemetry a DependencyTelemetry a používá se k určení korelace na portálu.

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

Rozhraní: IApplicationIdProvider

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

V sadě Microsoft.ApplicationInsights SDK poskytujeme dvě implementace: a ApplicationInsightsApplicationIdProvider DictionaryApplicationIdProvider .

ApplicationInsightsApplicationIdProvider

Toto je obálka kolem našeho rozhraní API pro profil. Bude ohrožovat požadavky a výsledky ukládání do 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 tato hodnota nastavená na https://dc.services.visualstudio.com/api/profiles/{0}/appId . Pokud pro tuto konfiguraci potřebujete nakonfigurovat proxy server, doporučujeme vytvořit proxy základní adresu včetně adresy /api/profiles/ {0} /appId. Všimněte si, že za běhu se za {0} běhu na požadavek 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

Jedná se o statického poskytovatele, který bude spoléhat na nakonfigurované páry instrumentace a ID aplikace.

Tato třída má vlastnost , což je slovníkový řetězec<řetězec, řetězec> dvojice instrumentační klíč Defined k ID aplikace.

Tato třída má volitelnou vlastnost, kterou lze použít ke konfiguraci jiného zprostředkovatele pro použití v případě požadavku na instrumentační klíč, který ve vaší Next konfiguraci neexistuje.

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

Další kroky

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

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

Ohodnoťte vaše zkušenosti

Moduly telemetrie (ASP.NET)

Sledování závislostí

Kolektor výkonu

Application Insights telemetrie diagnostiky

Vývojářský režim

Sledování webových žádostí

Sledování výjimek

Sledování EventSource

Sledování událostí ETW

Microsoft. ApplicationInsights

Kanál telemetrie

Inicializátory telemetrie (ASP.NET)

Procesory telemetrie (ASP.NET)

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

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

Instrumentační klíč

Zprostředkovatel ApplicationId

Rozhraní: IApplicationIdProvider

ApplicationInsightsApplicationIdProvider

Příklad konfigurace prostřednictvím ApplicationInsights.config:

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

DictionaryApplicationIdProvider

Příklad konfigurace prostřednictvím ApplicationInsights.config:

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

Další kroky