Delen via

De Application Insights-SDK configureren met ApplicationInsights.config of .xml

  • Artikel

De .NET SDK van Application Insights bestaat uit veel NuGet-pakketten. Het kernpakket biedt de API voor het verzenden van telemetrie naar Application Insights. Meer pakketten bieden telemetriemodules en initialisatiefuncties voor het automatisch bijhouden van telemetrie vanuit uw toepassing en de bijbehorende context. Door het configuratiebestand aan te passen, kunt u telemetriemodules en initialisatiemodules in- of uitschakelen. U kunt ook parameters voor sommige parameters instellen.

Notitie

De volgende documentatie is afhankelijk van de klassieke Application Insights-API. Het langetermijnplan voor Application Insights is het verzamelen van gegevens met behulp van OpenTelemetry. Zie Azure Monitor OpenTelemetry inschakelen voor .NET-, Node.js-, Python- en Java-toepassingen en onze OpenTelemetry Roadmap voor meer informatie. Migratierichtlijnen zijn beschikbaar voor .NET, Node.js en Python.

Het configuratiebestand heeft de naam ApplicationInsights.config of ApplicationInsights.xml. De naam is afhankelijk van het type toepassing. Deze wordt automatisch toegevoegd aan uw project wanneer u de meeste versies van de SDK installeert. Wanneer u de geautomatiseerde ervaring van de Visual Studio-sjabloonprojecten gebruikt die Ondersteuning bieden voor >Application Insights-telemetrie toevoegen, wordt het bestand gemaakt in de hoofdmap van het ApplicationInsights.config project. Wanneer deze is gecompileerd, wordt deze gekopieerd naar de bin-map. Het wordt ook toegevoegd aan een web-app door Application Insights Agent op een IIS-server. Het configuratiebestand wordt genegeerd als de extensie voor Azure-websites of de extensie voor Virtuele Azure-machines en virtuele-machineschaalsets wordt gebruikt.

Er is geen equivalent bestand om de SDK op een webpagina te beheren.

In dit artikel worden de secties beschreven die u in het configuratiebestand ziet, hoe ze de onderdelen van de SDK beheren en welke NuGet-pakketten deze onderdelen laden.

Notitie

De ApplicationInsights.config instructies en .xml zijn niet van toepassing op de .NET Core SDK. Als u .NET Core-toepassingen wilt configureren, volgt u de instructies in Application Insights voor ASP.NET Core-toepassingen.

Telemetriemodules (ASP.NET)

Elke telemetriemodule verzamelt een specifiek type gegevens en gebruikt de kern-API om de gegevens te verzenden. De modules worden geïnstalleerd door verschillende NuGet-pakketten, die ook de vereiste regels toevoegen aan het .config-bestand.

Er is een knooppunt in het configuratiebestand voor elke module. Als u een module wilt uitschakelen, verwijdert u het knooppunt of markeert u het uit.

Afhankelijkheid bijhouden

Met afhankelijkheidstracering worden telemetriegegevens verzameld over aanroepen die uw app uitvoert voor databases en externe services en databases. Als u wilt toestaan dat deze module werkt op een IIS-server, moet u Application Insights Agent installeren.

U kunt ook uw eigen code voor het bijhouden van afhankelijkheden schrijven met behulp van de TrackDependency-API.

Afhankelijkheden kunnen automatisch worden opgehaald zonder uw code te wijzigen met behulp van op agents gebaseerde (codeloze) attach. Als u deze wilt gebruiken in Azure-web-apps, schakelt u de Application Insights-extensie in. Als u deze wilt gebruiken in een Azure-VM of een virtuele-machineschaalset van Azure, schakelt u de toepassingsbewakingsextensie in voor VM's en virtuele-machineschaalsets.

Prestatieverzamelaar

De prestatieverzamelaar verzamelt systeemprestatiemeteritems, zoals CPU, geheugen en netwerkbelasting van IIS-installaties. U kunt opgeven welke tellers moeten worden verzameld, inclusief prestatiemeteritems die u zelf hebt ingesteld.

Diagnostische telemetrie van Application Insights

De DiagnosticsTelemetryModule klasse rapporteert fouten in de Application Insights-instrumentatiecode zelf. Voorbeelden zijn als de code geen toegang heeft tot prestatiemeteritems of als ITelemetryInitializer er een uitzondering wordt gegenereerd. Traceer telemetrie die door deze module wordt bijgehouden, wordt weergegeven in diagnostische zoekopdrachten.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Microsoft.ApplicationInsights NuGet-pakket. Als u dit pakket alleen installeert, wordt het bestand ApplicationInsights.config niet automatisch gemaakt.

Ontwikkelaarsmodus

De DeveloperModeWithDebuggerAttachedTelemetryModule klasse dwingt de Application Insights TelemetryChannel om gegevens onmiddellijk, één telemetrie-item tegelijk, te verzenden wanneer een foutopsporingsprogramma is gekoppeld aan het toepassingsproces. Dit ontwerp vermindert de tijd tussen het moment waarop uw toepassing telemetrie bijhoudt en wanneer deze wordt weergegeven in de Application Insights-portal. Dit veroorzaakt aanzienlijke overhead in CPU- en netwerkbandbreedte.

Tracering van webaanvragen

Bijhouden van webaanvragen rapporteert de reactietijd en resultaatcode van HTTP-aanvragen.

Uitzonderingen bijhouden

De ExceptionTrackingTelemetryModule klasse houdt niet-verwerkte uitzonderingen in uw web-app bij. Zie Fouten en uitzonderingen voor meer informatie.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • Microsoft.ApplicationInsights.Web NuGet-pakket.
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: Houdt niet-uitgevoerde taak bij. Uitzonderingen.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: houdt niet-verwerkte uitzonderingen bij voor werkrollen, Windows-services en consoletoepassingen.
  • Application Insights Windows Server NuGet-pakket.

EventSource-tracering

Met de EventSourceTelemetryModule klasse kunt u EventSource-gebeurtenissen configureren die als traceringen naar Application Insights worden verzonden. Zie EventSource-gebeurtenissen gebruiken voor informatie over het bijhouden van EventSource-gebeurtenissen.

ETW-gebeurtenissen bijhouden

Met de EtwCollectorTelemetryModule klasse kunt u gebeurtenissen van ETW-providers configureren die als traceringen naar Application Insights worden verzonden. Zie ETW-gebeurtenissen gebruiken voor informatie over het bijhouden van ETW-gebeurtenissen.

Microsoft.ApplicationInsights

Het Microsoft.ApplicationInsights pakket biedt de kern-API van de SDK. De andere telemetriemodules gebruiken deze API. U kunt deze ook gebruiken om uw eigen telemetrie te definiëren.

  • Geen vermelding in ApplicationInsights.config.
  • Microsoft.ApplicationInsights NuGet-pakket. Als u deze NuGet alleen installeert, wordt er geen .config-bestand gegenereerd.

Telemetriekanaal

Het telemetriekanaal beheert buffering en overdracht van telemetrie naar de Application Insights-service.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel is het standaardkanaal voor webtoepassingen. Het buffert gegevens in het geheugen en maakt gebruik van mechanismen voor opnieuw proberen en lokale schijfopslag voor betrouwbaardere telemetrielevering.
  • Microsoft.ApplicationInsights.InMemoryChannel is een lichtgewicht telemetriekanaal. Deze wordt gebruikt als er geen ander kanaal is geconfigureerd.

Initialisatiefuncties voor telemetrie (ASP.NET)

Met initialisatiefuncties voor telemetrie worden contexteigenschappen ingesteld die samen met elk item van telemetrie worden verzonden.

U kunt uw eigen initializers schrijven om contexteigenschappen in te stellen.

De standaard initializers zijn allemaal ingesteld door de web- of WindowsServer NuGet-pakketten:

  • AccountIdTelemetryInitializer stelt de AccountId eigenschap in.

  • AuthenticatedUserIdTelemetryInitializer stelt de AuthenticatedUserId eigenschap in zoals ingesteld door de JavaScript SDK.

  • AzureRoleEnvironmentTelemetryInitializer werkt de RoleName en RoleInstance eigenschappen van de Device context voor alle telemetrie-items bij met informatie die is geëxtraheerd uit de Azure Runtime-omgeving.

  • BuildInfoConfigComponentVersionTelemetryInitializer werkt de Version eigenschap van de Component context voor alle telemetrie-items bij met de waarde die is geëxtraheerd uit het BuildInfo.config bestand dat door MS Build wordt geproduceerd.

  • ClientIpHeaderTelemetryInitializer werkt de Ip eigenschap van de Location context van alle telemetrie-items bij op basis van de X-Forwarded-For HTTP-header van de aanvraag.

  • DeviceTelemetryInitializer werkt de volgende eigenschappen van de Device context voor alle telemetrie-items bij.

    • Type is ingesteld op PC.
    • Id is ingesteld op de domeinnaam van de computer waarop de webtoepassing wordt uitgevoerd.
    • OemName is ingesteld op de waarde die uit het Win32_ComputerSystem.Manufacturer veld is geëxtraheerd met behulp van WMI.
    • Model is ingesteld op de waarde die uit het Win32_ComputerSystem.Model veld is geëxtraheerd met behulp van WMI.
    • NetworkType is ingesteld op de waarde die uit de NetworkInterface eigenschap is geëxtraheerd.
    • Language is ingesteld op de naam van de CurrentCulture eigenschap.

  • DomainNameRoleInstanceTelemetryInitializer werkt de RoleInstance eigenschap van de Device context voor alle telemetrie-items bij met de domeinnaam van de computer waarop de webtoepassing wordt uitgevoerd.

  • OperationNameTelemetryInitializer werkt de Name eigenschap van RequestTelemetry en de Name eigenschap van de Operation context van alle telemetrie-items bij op basis van de HTTP-methode en de namen van de ASP.NET MVC-controller en actie die wordt aangeroepen om de aanvraag te verwerken.

  • OperationIdTelemetryInitializer of OperationCorrelationTelemetryInitializer werkt de Operation.Id contexteigenschap bij van alle telemetrie-items die worden bijgehouden tijdens het verwerken van een aanvraag met de automatisch gegenereerde RequestTelemetry.Idaanvraag.

  • SessionTelemetryInitializer werkt de Id eigenschap van de Session context voor alle telemetrie-items bij met waarde die is geëxtraheerd uit de ai_session cookie die is gegenereerd door de ApplicationInsights JavaScript-instrumentatiecode die wordt uitgevoerd in de browser van de gebruiker.

  • SyntheticTelemetryInitializer of SyntheticUserAgentTelemetryInitializer werkt de User, Sessionen Operation contexteigenschappen van alle telemetrie-items bij die worden bijgehouden bij het verwerken van een aanvraag van een synthetische bron, zoals een beschikbaarheidstest of een zoekmachinebot. Standaard wordt in Metrics Explorer geen synthetische telemetrie weergegeven.

    De <Filters> set die eigenschappen van de aanvragen identificeert.

  • UserTelemetryInitializer werkt de Id en AcquisitionDate eigenschappen van de User context voor alle telemetrie-items bij met waarden die zijn geëxtraheerd uit de ai_user cookie die is gegenereerd door de JavaScript-instrumentatiecode van Application Insights die wordt uitgevoerd in de browser van de gebruiker.

  • WebTestTelemetryInitializer stelt de gebruikers-id, sessie-id en synthetische broneigenschappen in voor HTTP-aanvragen die afkomstig zijn van beschikbaarheidstests. De <Filters> set die eigenschappen van de aanvragen identificeert.

Voor .NET-toepassingen die worden uitgevoerd in Azure Service Fabric, kunt u het Microsoft.ApplicationInsights.ServiceFabric NuGet-pakket opnemen. Dit pakket bevat een FabricTelemetryInitializer eigenschap, waarmee Service Fabric-eigenschappen worden toegevoegd aan telemetrie-items. Zie de GitHub-pagina over de eigenschappen die door dit NuGet-pakket zijn toegevoegd voor meer informatie.

Telemetrieprocessors (ASP.NET)

Telemetrieprocessors kunnen elk telemetrie-item filteren en wijzigen voordat het van de SDK naar de portal wordt verzonden.

U kunt uw eigen telemetrieprocessors schrijven.

Adaptieve steekproeftelemetrieprocessor (van 2.0.0-beta3)

Deze functionaliteit is standaard ingeschakeld. Als uw app aanzienlijke telemetrie verzendt, verwijdert deze processor een deel ervan.


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

De parameter biedt het doel dat het algoritme probeert te bereiken. Elk exemplaar van de SDK werkt onafhankelijk. Dus als uw server een cluster van verschillende computers is, wordt het werkelijke volume van telemetrie dienovereenkomstig vermenigvuldigd.

Meer informatie over steekproeven.

Telemetrieprocessor met vaste snelheid (van 2.0.0-beta1)

Er is ook een standaard steekproeftelemetrieprocessor (van 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

Zie verbindingsreeks codevoorbeelden.

InstrumentationKey

Notitie

Op 31 maart 2025 eindigt de ondersteuning voor opname van instrumentatiesleutels. Opname van instrumentatiesleutels blijft werken, maar we bieden geen updates of ondersteuning meer voor de functie. Overgang naar verbindingsreeks s om te profiteren van nieuwe mogelijkheden.

Deze instelling bepaalt de Application Insights-resource waarin uw gegevens worden weergegeven. Doorgaans maakt u een afzonderlijke resource, met een afzonderlijke sleutel, voor elk van uw toepassingen.

Als u de sleutel dynamisch wilt instellen, bijvoorbeeld als u resultaten van uw toepassing naar verschillende resources wilt verzenden, kunt u de sleutel weglaten uit het configuratiebestand en deze in plaats daarvan instellen in code.

Als u de sleutel wilt instellen voor alle exemplaren van TelemetryClient, inclusief standaardtelemetriemodules, voert u deze stap uit in een initialisatiemethode, zoals global.aspx.cs in een ASP.NET-service:

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

Als u een specifieke set gebeurtenissen naar een andere resource wilt verzenden, kunt u de sleutel voor een specifieke telemetrieclient instellen:


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

Als u een nieuwe sleutel wilt ophalen, maakt u een nieuwe resource in de Application Insights-portal.

ApplicationId-provider

De provider is beschikbaar vanaf v2.6.0.

Het doel van deze provider is om een toepassings-id op te zoeken op basis van een instrumentatiesleutel. De toepassings-id is opgenomen in RequestTelemetry en DependencyTelemetry wordt gebruikt om de correlatie in de portal te bepalen.

Deze functionaliteit is beschikbaar door in code of in het configuratiebestand in te stellen TelemetryConfiguration.ApplicationIdProvider .

Interface: IApplicationIdProvider

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

We bieden twee implementaties in de Microsoft.ApplicationInsights SDK: ApplicationInsightsApplicationIdProvider en DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Deze wrapper is voor onze profiel-API. Hiermee worden aanvragen beperkt en worden de resultaten in de cache opgeslagen.

Deze provider wordt toegevoegd aan uw configuratiebestand wanneer u Microsoft.ApplicationInsights.DependencyCollector of Microsoft.ApplicationInsights.Web installeert.

Deze klasse heeft een optionele eigenschap ProfileQueryEndpoint. Deze is standaard ingesteld op https://dc.services.visualstudio.com/api/profiles/{0}/appId. Als u een proxy voor deze configuratie wilt configureren, raden we u aan om het basisadres te proxyn en op te nemen "/api/profiles/{0}/appId". Een {0} wordt tijdens runtime per aanvraag vervangen door de instrumentatiesleutel.

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

Voorbeeldconfiguratie via code

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Deze statische provider is afhankelijk van uw geconfigureerde instrumentatiesleutel-/toepassings-id-paren.

Deze klasse heeft de Defined eigenschap, een Dictionary<string,string> van instrumentatiesleutel-/toepassings-id-paren.

Deze klasse heeft de optionele eigenschap Next, die kan worden gebruikt om een andere provider te configureren die moet worden gebruikt wanneer een instrumentatiesleutel wordt aangevraagd die niet bestaat in uw configuratie.

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

Voorbeeldconfiguratie via code

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

Momentopnameverzameling configureren voor ASP.NET toepassingen

Configureer een verzameling momentopnamen voor ASP.NET toepassingen.

Volgende stappen

Meer informatie over de API