Konfigurera Application Insights SDK med ApplicationInsights.config eller .xml

  • Artikel

Application Insights .NET SDK består av många NuGet-paket. Kärnpaketet tillhandahåller API:et för att skicka telemetri till Application Insights. Fler paket tillhandahåller telemetrimoduler och initierare för automatisk spårning av telemetri från ditt program och dess kontext. Genom att justera konfigurationsfilen kan du aktivera eller inaktivera telemetrimoduler och initierare. Du kan också ange parametrar för vissa av dem.

Kommentar

Följande dokumentation förlitar sig på det klassiska API:et Application Insights. Den långsiktiga planen för Application Insights är att samla in data med OpenTelemetry. Mer information finns i Aktivera Azure Monitor OpenTelemetry för .NET-, Node.js-, Python- och Java-program.

Konfigurationsfilen heter ApplicationInsights.config eller ApplicationInsights.xml. Namnet beror på typen av program. Det läggs automatiskt till i projektet när du installerar de flesta versioner av SDK:et. När du använder den automatiserade upplevelsen från Visual Studio-mallprojekten som stöder Add>Application Insights TelemetryApplicationInsights.config skapas filen som standard i projektrotmappen. När den kompileras kopieras den till mappen bin. Den läggs också till i en webbapp av Application Insights Agent på en IIS-server. Konfigurationsfilen ignoreras om tillägget för Azure-webbplatser eller tillägget för virtuella Azure-datorer och vm-skalningsuppsättningar används.

Det finns ingen motsvarande fil som styr SDK: t på en webbsida.

Den här artikeln beskriver de avsnitt som du ser i konfigurationsfilen, hur de styr komponenterna i SDK:n och vilka NuGet-paket som läser in dessa komponenter.

Kommentar

Instruktionerna ApplicationInsights.config och .xml gäller inte för .NET Core SDK. Om du vill konfigurera .NET Core-program följer du anvisningarna i Application Insights för ASP.NET Core-program.

Telemetrimoduler (ASP.NET)

Varje telemetrimodul samlar in en specifik typ av data och använder kärn-API:et för att skicka data. Modulerna installeras av olika NuGet-paket, som också lägger till de nödvändiga raderna i .config-filen.

Det finns en nod i konfigurationsfilen för varje modul. Om du vill inaktivera en modul tar du bort noden eller kommenterar ut den.

Beroendespårning

Beroendespårning samlar in telemetri om anrop som din app gör till databaser och externa tjänster och databaser. För att den här modulen ska fungera på en IIS-server måste du installera Application Insights-agenten.

Du kan också skriva din egen kod för beroendespårning med hjälp av TrackDependency-API:et.

Beroenden kan samlas in automatiskt utan att ändra koden med hjälp av agentbaserad (kodlös) koppling. Aktivera Application Insights-tillägget om du vill använda det i Azure-webbappar. Om du vill använda den på en virtuell Azure-dator eller en skalningsuppsättning för virtuella Azure-datorer aktiverar du tillägget Programövervakning för virtuella datorer och VM-skalningsuppsättningar.

Prestandainsamlare

Prestandainsamlaren samlar in systemprestandaräknare, till exempel PROCESSOR, minne och nätverksbelastning från IIS-installationer. Du kan ange vilka räknare som ska samlas in, inklusive prestandaräknare som du har konfigurerat själv.

Telemetri för Application Insights-diagnostik

Klassen DiagnosticsTelemetryModule rapporterar fel i själva Application Insights-instrumentationskoden. Exempel är om koden inte kan komma åt prestandaräknare eller om ITelemetryInitializer genererar ett undantag. Spårningstelemetri som spåras av den här modulen visas i diagnostiksökningen.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Microsoft.ApplicationInsights NuGet-paket. Om du bara installerar det här paketet skapas inte ApplicationInsights.config-filen automatiskt.

Utvecklarläge

Klassen DeveloperModeWithDebuggerAttachedTelemetryModule tvingar Application Insights TelemetryChannel att skicka data omedelbart, ett telemetriobjekt i taget, när ett felsökningsprogram är kopplat till programprocessen. Den här designen minskar tiden mellan det ögonblick då programmet spårar telemetri och när det visas i Application Insights-portalen. Det orsakar betydande omkostnader i processor- och nätverksbandbredd.

Spårning av webbbegäranden

Spårning av webbbegäran rapporterar svarstid och resultatkod för HTTP-begäranden.

Undantagsspårning

Klassen ExceptionTrackingTelemetryModule spårar ohanterade undantag i webbappen. Mer information finns i Fel och undantag.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • Microsoft.ApplicationInsights.Web NuGet-paket.
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: Spårar oobserverad uppgift. Undantag.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: Spårar ohanterade undantag för arbetsroller, Windows-tjänster och konsolprogram.
  • Application Insights Windows Server NuGet-paket.

EventSource-spårning

Med EventSourceTelemetryModule klassen kan du konfigurera EventSource-händelser som ska skickas till Application Insights som spårningar. Information om hur du spårar EventSource-händelser finns i Använda EventSource-händelser.

Spårning av ETW-händelser

Med EtwCollectorTelemetryModule klassen kan du konfigurera händelser från ETW-leverantörer som ska skickas till Application Insights som spårningar. Information om hur du spårar ETW-händelser finns i Använda ETW-händelser.

Microsoft.ApplicationInsights

Paketet Microsoft.ApplicationInsights tillhandahåller SDK:ns kärn-API . De andra telemetrimodulerna använder det här API:et. Du kan också använda den för att definiera din egen telemetri.

Telemetrikanal

Telemetrikanalen hanterar buffring och överföring av telemetri till Application Insights-tjänsten.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel är standardkanalen för webbprogram. Den buffrar data i minnet och använder mekanismer för återförsök och lokal disklagring för mer tillförlitlig telemetrileverans.
  • Microsoft.ApplicationInsights.InMemoryChannel är en lätt telemetrikanal. Den används om ingen annan kanal har konfigurerats.

Telemetriinitierare (ASP.NET)

Telemetriinitierare anger kontextegenskaper som skickas tillsammans med varje telemetriobjekt.

Du kan skriva egna initierare för att ange kontextegenskaper.

Standardinitierarna anges antingen av webben eller WindowsServer NuGet-paket:

  • AccountIdTelemetryInitializer anger egenskapen AccountId .

  • AuthenticatedUserIdTelemetryInitializer anger egenskapen AuthenticatedUserId enligt javascript-SDK:t.

  • AzureRoleEnvironmentTelemetryInitializeruppdaterar kontextens RoleNameDevice egenskaper och RoleInstance för alla telemetriobjekt med information som extraherats från Azure-körningsmiljön.

  • BuildInfoConfigComponentVersionTelemetryInitializerVersion uppdaterar egenskapen för kontexten Component för alla telemetriobjekt med värdet som extraheras från BuildInfo.config filen som skapas av MS Build.

  • ClientIpHeaderTelemetryInitializer uppdaterar egenskapen för Ip kontexten för Location alla telemetriobjekt baserat på X-Forwarded-For HTTP-huvudet för begäran.

  • DeviceTelemetryInitializer uppdaterar följande egenskaper för kontexten Device för alla telemetriobjekt.

    • Type är inställt på PC.
    • Id är inställt på domännamnet för den dator där webbprogrammet körs.
    • OemName anges till det värde som extraheras från fältet Win32_ComputerSystem.Manufacturer med hjälp av WMI.
    • Model anges till det värde som extraheras från fältet Win32_ComputerSystem.Model med hjälp av WMI.
    • NetworkType är inställt på värdet som extraheras från NetworkInterface egenskapen.
    • Language är inställt på egenskapens CurrentCulture namn.

  • DomainNameRoleInstanceTelemetryInitializerRoleInstance uppdaterar egenskapen för kontexten Device för alla telemetriobjekt med domännamnet för den dator där webbprogrammet körs.

  • OperationNameTelemetryInitializerName uppdaterar egenskapen RequestTelemetry för och Name egenskapen för kontexten Operation för alla telemetriobjekt baserat på HTTP-metoden och namnen på den ASP.NET MVC-styrenhet och åtgärd som anropas för att bearbeta begäran.

  • OperationIdTelemetryInitializer eller OperationCorrelationTelemetryInitializer uppdaterar kontextegenskapen för Operation.Id alla telemetriobjekt som spåras när en begäran hanteras med den automatiskt genererade RequestTelemetry.Id.

  • SessionTelemetryInitializerId uppdaterar egenskapen för kontexten Session för alla telemetriobjekt med värde som extraherats från cookien ai_session som genereras av ApplicationInsights JavaScript-instrumentationskoden som körs i användarens webbläsare.

  • SyntheticTelemetryInitializereller SyntheticUserAgentTelemetryInitializer uppdaterar egenskaperna , Sessionoch Operation kontext för Useralla telemetriobjekt som spåras vid hantering av en begäran från en syntetisk källa, till exempel ett tillgänglighetstest eller en sökmotorrobot. Som standard visar metrics Explorer inte syntetisk telemetri.

    Uppsättningen <Filters> som identifierar egenskaperna för begäranden.

  • UserTelemetryInitializeruppdaterar kontextens IdUser egenskaper och AcquisitionDate för alla telemetriobjekt med värden som extraheras från cookien ai_user som genereras av Application Insights JavaScript-instrumentationskoden som körs i användarens webbläsare.

  • WebTestTelemetryInitializer anger användar-ID, sessions-ID och syntetiska källegenskaper för HTTP-begäranden som kommer från tillgänglighetstester. Uppsättningen <Filters> som identifierar egenskaperna för begäranden.

För .NET-program som körs i Azure Service Fabric kan du inkludera Microsoft.ApplicationInsights.ServiceFabric NuGet-paketet. Det här paketet innehåller en FabricTelemetryInitializer egenskap som lägger till Service Fabric-egenskaper till telemetriobjekt. Mer information finns på GitHub-sidan om de egenskaper som lagts till av det här NuGet-paketet.

Telemetriprocessorer (ASP.NET)

Telemetriprocessorer kan filtrera och ändra varje telemetriobjekt innan det skickas från SDK:t till portalen.

Du kan skriva egna telemetriprocessorer.

Telemetriprocessor för anpassningsbar sampling (från 2.0.0-beta3)

Den här funktionen är aktiverad som standard. Om din app skickar betydande telemetri tar den här processorn bort en del av den.


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

Parametern ger det mål som algoritmen försöker uppnå. Varje instans av SDK:t fungerar oberoende av varandra. Om servern är ett kluster med flera datorer multipliceras alltså den faktiska telemetrivolymen.

Läs mer om sampling.

Telemetriprocessor för fast sampling (från 2.0.0-beta1)

Det finns också en standardtelemetriprocessor för sampling (från 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

Se anslutningssträng kodexempel.

InstrumentationKey

Kommentar

Stödet för inmatning av instrumentationsnycklar upphör den 31 mars 2025. Inmatningen av instrumenteringsnyckeln fortsätter att fungera, men vi kommer inte längre att tillhandahålla uppdateringar eller stöd för funktionen. Övergå till anslutningssträng för att dra nytta av nya funktioner.

Den här inställningen avgör i vilken Application Insights-resurs dina data visas. Vanligtvis skapar du en separat resurs med en separat nyckel för vart och ett av dina program.

Om du vill ange nyckeln dynamiskt, till exempel om du vill skicka resultat från programmet till olika resurser, kan du utelämna nyckeln från konfigurationsfilen och ange den i kod i stället.

Om du vill ange nyckeln för alla instanser av TelemetryClient, inklusive standardtelemetrimoduler, gör du det här steget i en initieringsmetod, till exempel global.aspx.cs i en ASP.NET-tjänst:

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

Om du vill skicka en specifik uppsättning händelser till en annan resurs kan du ange nyckeln för en specifik telemetriklient:


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

Om du vill hämta en ny nyckel skapar du en ny resurs i Application Insights-portalen.

ApplicationId-provider

Providern är tillgänglig från och med v2.6.0.

Syftet med den här providern är att söka efter ett program-ID baserat på en instrumentationsnyckel. Program-ID ingår i RequestTelemetry och DependencyTelemetry används för att fastställa korrelation i portalen.

Den här funktionen är tillgänglig genom att ange TelemetryConfiguration.ApplicationIdProvider antingen i kod eller i konfigurationsfilen.

Gränssnitt: IApplicationIdProvider

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

Vi tillhandahåller två implementeringar i Microsoft.ApplicationInsights SDK: ApplicationInsightsApplicationIdProvider och DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Den här omslutningen är för vårt profil-API. Det begränsar begäranden och cacheresultat.

Den här providern läggs till i konfigurationsfilen när du installerar antingen Microsoft.ApplicationInsights.DependencyCollector eller Microsoft.ApplicationInsights.Web.

Den här klassen har en valfri egenskap ProfileQueryEndpoint. Som standard är den inställd på https://dc.services.visualstudio.com/api/profiles/{0}/appId. Om du behöver konfigurera en proxy för den här konfigurationen rekommenderar vi att du proxyserverr basadressen och inkluderar "/api/profiles/{0}/appId". A {0} ersätts vid körning per begäran med instrumentationsnyckeln.

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

Exempelkonfiguration via kod

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Den här statiska providern förlitar sig på dina konfigurerade instrumentationsnyckel/program-ID-par.

Den här klassen har Defined egenskapen, som är en Dictionary<string,string> av instrumentationsnyckel/program-ID-par.

Den här klassen har den valfria egenskapen Next, som kan användas för att konfigurera en annan provider att använda när en instrumentationsnyckel begärs som inte finns i konfigurationen.

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

Exempelkonfiguration via kod

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

Konfigurera ögonblicksbildsamling för ASP.NET program

Konfigurera en samling ögonblicksbilder för ASP.NET program.

Nästa steg

Läs mer om API:et