Az Alkalmazás Elemzések SDK konfigurálása az Application Elemzések.config vagy .xml

  • Cikk

Az application Elemzések .NET SDK számos NuGet-csomagból áll. Az alapcsomag biztosítja az API-t, amely telemetriát küld az alkalmazásnak Elemzések. További csomagok telemetriai modulokat és inicializálókat biztosítanak az alkalmazásból és környezetéből származó telemetriai adatok automatikus nyomon követéséhez. A konfigurációs fájl módosításával engedélyezheti vagy letilthatja a telemetriai modulokat és inicializálókat. Néhány paramétert is beállíthat.

Feljegyzés

Az alábbi dokumentáció az Alkalmazás Elemzések klasszikus API-ra támaszkodik. Az Alkalmazás Elemzések hosszú távú terve az Adatok gyűjtése Az OpenTelemetria használatával. További információ: Az Azure Monitor OpenTelemetria engedélyezése .NET-, Node.js-, Python- és Java-alkalmazásokhoz.

A konfigurációs fájl neve vagy ApplicationInsights.xmlneve ApplicationInsights.config . A név az alkalmazás típusától függ. A rendszer automatikusan hozzáadja a projekthez az SDK legtöbb verziójának telepítésekor. Alapértelmezés szerint az Alkalmazás hozzáadása>Elemzések telemetriát támogató Visual Studio-sablonprojektek automatizált felületének használatakor a ApplicationInsights.config fájl a projekt gyökérmappájában jön létre. Fordításkor a rendszer a bin mappába másolja. Az Alkalmazás Elemzések-ügynök hozzáadja egy webalkalmazáshoz egy IIS-kiszolgálón. A konfigurációs fájl figyelmen kívül lesz hagyva, ha az Azure-webhelyek bővítményét vagy az Azure-beli virtuális gépek és virtuálisgép-méretezési csoportok bővítményét használja.

A weblap SDK-jának szabályozásához nincs megfelelő fájl.

Ez a cikk ismerteti a konfigurációs fájlban látható szakaszokat, az SDK összetevőinek vezérlését, és hogy mely NuGet-csomagok töltik be ezeket az összetevőket.

Feljegyzés

Az ApplicationInsights.config és .xml utasítások nem vonatkoznak a .NET Core SDK-ra. A .NET Core-alkalmazások konfigurálásához kövesse az Alkalmazás Elemzések ASP.NET Core-alkalmazásokra vonatkozó utasításait.

Telemetriai modulok (ASP.NET)

Minden telemetriai modul egy adott adattípust gyűjt, és az alapvető API használatával küldi el az adatokat. A modulokat különböző NuGet-csomagok telepítik, amelyek a szükséges sorokat is hozzáadják a .config fájlhoz.

Minden modulhoz tartozik egy csomópont a konfigurációs fájlban. Egy modul letiltásához törölje a csomópontot, vagy fűzzön hozzá megjegyzést.

Függőség nyomon követése

A függőségek nyomon követése telemetriát gyűjt az alkalmazás által az adatbázisokba, külső szolgáltatásokba és adatbázisokba irányuló hívásokról. Ahhoz, hogy ez a modul egy IIS-kiszolgálón működjön, telepítenie kell az Application Elemzések Agentet.

Saját függőségkövetési kódot is írhat a TrackDependency API használatával.

A függőségek az ügynökalapú (kód nélküli) csatolással automatikusancolhatók anélkül, hogy módosítanák a kódot. Ha azure-webalkalmazásokban szeretné használni, engedélyezze az Alkalmazás Elemzések bővítményt. Ha Azure-beli virtuális gépen vagy Azure-beli virtuálisgép-méretezési csoportban szeretné használni, engedélyezze az Alkalmazásfigyelés bővítményt virtuális gépekhez és virtuálisgép-méretezési csoportokhoz.

Teljesítménygyűjtő

A teljesítménygyűjtő összegyűjti a rendszer teljesítményszámlálóit, például a CPU-t, a memóriát és a hálózati terhelést az IIS-telepítésekből. Megadhatja, hogy mely számlálókat gyűjtse össze, beleértve a saját maga által beállított teljesítményszámlálókat is.

Alkalmazás Elemzések diagnosztikai telemetriai adatai

Az DiagnosticsTelemetryModule osztály az alkalmazás Elemzések rendszerállapot-kód hibáit jelenti. Ilyen például, ha a kód nem fér hozzá a teljesítményszámlálókhoz, vagy ITelemetryInitializer kivételt jelez. A modul által követett nyomkövetési telemetria megjelenik a Diagnosztikai keresésben.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Microsoft.Application Elemzések NuGet-csomag. Ha csak ezt a csomagot telepíti, az alkalmazás Elemzések.config fájl nem jön létre automatikusan.

Fejlesztői mód

Az DeveloperModeWithDebuggerAttachedTelemetryModule osztály arra kényszeríti az alkalmazás ElemzésekTelemetryChannel, hogy azonnal küldjön adatokat, egyszerre egy telemetriai elemet, amikor egy hibakereső csatlakozik az alkalmazás folyamatához. Ez a kialakítás csökkenti az alkalmazás telemetriai adatainak nyomon követése és az Alkalmazás Elemzések portálon való megjelenése közötti időt. Jelentős többletterhelést okoz a processzor- és hálózati sávszélességben.

Webes kérések nyomon követése

A webes kérések nyomon követése a HTTP-kérések válaszidejének és eredménykódjának jelentését jelenti.

Kivételkövetés

Az ExceptionTrackingTelemetryModule osztály nyomon követi a nem kezelt kivételeket a webalkalmazásban. További információ: Hibák és kivételek.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • Microsoft.Application Elemzések. Webes NuGet-csomag.
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: Nyomon követi a nem figyelt tevékenységet. Kivételek.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: Nyomon követi a feldolgozói szerepkörök, a Windows-szolgáltatások és a konzolalkalmazások kezeletlen kivételét.
  • Alkalmazás Elemzések Windows Server NuGet-csomag.

EventSource-nyomkövetés

Az EventSourceTelemetryModule osztály lehetővé teszi eventSource-események konfigurálását, hogy nyomkövetésként küldhetők legyenek az alkalmazásnak Elemzések. Az EventSource-események nyomon követésével kapcsolatos információkért lásd: EventSource-események használata.

ETW eseménykövetés

Az EtwCollectorTelemetryModule osztály lehetővé teszi, hogy konfigurálja az ETW-szolgáltatóktól származó eseményeket, hogy nyomkövetésként elküldhetők legyenek az Alkalmazás Elemzések. Az ETW-események nyomon követésével kapcsolatos információkért lásd : ETW-események használata.

Microsoft.Application Elemzések

A Microsoft.ApplicationInsights csomag biztosítja az SDK alapvető API-ját . A többi telemetriai modul ezt az API-t használja. Azt is használhatja, hogy meghatározza a saját telemetriai.

  • Nincs bejegyzés az Application Elemzések.config alkalmazásban.
  • Microsoft.Application Elemzések NuGet-csomag. Ha csak ezt a NuGetet telepíti, a rendszer nem hoz létre .config fájlt.

Telemetriai csatorna

A telemetriai csatorna kezeli a telemetria pufferelését és átvitelét az Application Elemzések szolgáltatásba.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel a webalkalmazások alapértelmezett csatornája. Puffereli az adatokat a memóriában, és újrapróbálkozási mechanizmusokat és helyi lemeztárolókat alkalmaz a megbízhatóbb telemetriai kézbesítés érdekében.
  • Microsoft.ApplicationInsights.InMemoryChannel egy egyszerűsített telemetriai csatorna. Akkor használatos, ha nincs más csatorna konfigurálva.

Telemetriai inicializálók (ASP.NET)

A telemetriai inicializálók a telemetria minden elemével együtt elküldik a környezeti tulajdonságokat.

A környezettulajdonságok beállításához saját inicializálókat is írhat.

A standard inicializálókat a webes vagy a WindowsServer NuGet-csomagok állítják be:

  • AccountIdTelemetryInitializer beállítja a tulajdonságot AccountId .

  • AuthenticatedUserIdTelemetryInitializer A tulajdonságot a AuthenticatedUserId JavaScript SDK által beállított módon állítja be.

  • AzureRoleEnvironmentTelemetryInitializerRoleName az Azure futtatókörnyezetből kinyert információkkal frissíti az Device összes telemetriai elem környezetét és RoleInstance tulajdonságait.

  • BuildInfoConfigComponentVersionTelemetryInitializerVersion az MS Build által létrehozott fájlból BuildInfo.config kinyert értékkel frissíti az Component összes telemetriai elem környezetének tulajdonságát.

  • ClientIpHeaderTelemetryInitializer frissíti az IpLocation összes telemetriai elem környezetének tulajdonságát a X-Forwarded-For kérelem HTTP-fejléce alapján.

  • DeviceTelemetryInitializer az összes telemetriai elem környezetének Device alábbi tulajdonságait frissíti.

    • Type beállítás értéke : PC.
    • Id annak a számítógépnek a tartományneve, amelyen a webalkalmazás fut.
    • OemName a WMI használatával a Win32_ComputerSystem.Manufacturer mezőből kinyert értékre van állítva.
    • Model a WMI használatával a Win32_ComputerSystem.Model mezőből kinyert értékre van állítva.
    • NetworkType a tulajdonságból NetworkInterface kinyert értékre van állítva.
    • Language a tulajdonság nevére CurrentCulture van állítva.

  • DomainNameRoleInstanceTelemetryInitializer frissíti az RoleInstanceDevice összes telemetriai elem környezetének tulajdonságát annak a számítógépnek a tartománynevével, amelyen a webalkalmazás fut.

  • OperationNameTelemetryInitializer frissíti az Name összes telemetriai elem tulajdonságát RequestTelemetry és Name tulajdonságát Operation a HTTP-metódus alapján, valamint a kérés feldolgozásához meghívott ASP.NET MVC-vezérlő és művelet nevét.

  • OperationIdTelemetryInitializer vagy OperationCorrelationTelemetryInitializer frissíti az Operation.Id összes nyomon követett telemetriai elem környezeti tulajdonságát, miközben az automatikusan létrehozott RequestTelemetry.Idkérést kezeli.

  • SessionTelemetryInitializer frissíti a Id környezet tulajdonságát a Session felhasználó böngészőjében futó JavaScript-rendszerállapotkód által létrehozott cookie-ból ai_sessionApplicationInsights kinyert értékkel rendelkező összes telemetriai elem esetében.

  • SyntheticTelemetryInitializer vagy SyntheticUserAgentTelemetryInitializer frissíti az Userösszes követett telemetriai elem, Sessionpéldául a rendelkezésre állási teszt vagy Operation a keresőmotor-robot kéréseinek kezelésekor nyomon követett telemetriai elemek, illetve a környezet tulajdonságait. Alapértelmezés szerint a Metrikák kezelője nem jelenít meg szintetikus telemetriát.

    A <Filters> kérések tulajdonságait azonosító készlet.

  • UserTelemetryInitializerfrissíti az IdUser összes telemetriai elem környezetét és AcquisitionDate tulajdonságait a felhasználó böngészőjében futó Alkalmazás Elemzések JavaScript-eszközkód által létrehozott cookie-ból ai_user kinyert értékekkel.

  • WebTestTelemetryInitializerA rendelkezésre állási tesztekből származó HTTP-kérelmek felhasználói azonosítóját, munkamenet-azonosítóját és szintetikus forrástulajdonságait állítja be. A <Filters> kérések tulajdonságait azonosító készlet.

Az Azure Service Fabricben futó .NET-alkalmazásokhoz a NuGet-csomagot is belefoglalhatja Microsoft.ApplicationInsights.ServiceFabric . Ez a csomag tartalmaz egy tulajdonságot FabricTelemetryInitializer , amely Service Fabric-tulajdonságokat ad hozzá a telemetriai elemekhez. További információt a NuGet-csomag által hozzáadott tulajdonságokról a GitHub oldalán talál .

Telemetriai processzorok (ASP.NET)

A telemetriai processzorok szűrhetik és módosíthatják az egyes telemetriai elemeket, mielőtt az SDK-ból a portálra küldené őket.

Saját telemetriai processzorokat is írhat.

Adaptív mintavételezési telemetriafeldolgozó (2.0.0-béta3-tól)

Ez a funkció alapértelmezés szerint engedélyezve van. Ha az alkalmazás jelentős telemetriát küld, ez a processzor eltávolít belőle néhányat.


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

A paraméter megadja az algoritmus által elérni kívánt célt. Az SDK minden példánya egymástól függetlenül működik. Ha tehát a kiszolgáló több gépből álló fürt, a rendszer ennek megfelelően megszorozza a telemetriai adatok tényleges mennyiségét.

További információ a mintavételezésről.

Rögzített sebességű mintavételezési telemetriafeldolgozó (2.0.0-béta1-től)

Van egy szabványos mintavételezési telemetriai processzor is (2.0.1-től):


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

Csatlakozás ionString

Lásd kapcsolati sztring kódmintákat.

InstrumentationKey

Feljegyzés

2025. március 31-én megszűnik az eszközkulcsalapú betöltés támogatása. A rendszerállapot-kulcsok betöltése továbbra is működni fog, de a továbbiakban nem biztosítunk frissítéseket vagy támogatást a funkcióhoz. Váltás kapcsolati sztring az új képességek kihasználásához.

Ez a beállítás határozza meg az alkalmazás Elemzések erőforrást, amelyben az adatok megjelennek. Általában minden alkalmazáshoz külön erőforrást hoz létre, külön kulccsal.

Ha például dinamikusan szeretné beállítani a kulcsot, például ha az alkalmazásból szeretne eredményeket küldeni különböző erőforrásokba, kihagyhatja a kulcsot a konfigurációs fájlból, és ehelyett kódban állíthatja be.

Ha az összes példány kulcsát TelemetryClientbe szeretné állítani , beleértve a standard telemetriai modulokat is, hajtsa végre ezt a lépést egy inicializálási módszerben, például global.aspx.cs egy ASP.NET szolgáltatásban:

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

Ha egy adott eseménykészletet szeretne elküldeni egy másik erőforrásnak, beállíthatja egy adott telemetriai ügyfél kulcsát:


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

Új kulcs beszerzéséhez hozzon létre egy új erőforrást az Alkalmazás Elemzések portálon.

ApplicationId-szolgáltató

A szolgáltató a 2.6.0-s verziótól érhető el.

Ennek a szolgáltatónak az a célja, hogy egy eszközkulcson alapuló alkalmazásazonosítót keressen. Az alkalmazásazonosító szerepel a RequestTelemetry portálon, és DependencyTelemetry a korreláció meghatározására szolgál.

Ez a funkció a kódban vagy a konfigurációs fájlban való beállítással TelemetryConfiguration.ApplicationIdProvider érhető el.

Interfész: IApplicationIdProvider

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

Két implementációt biztosítunk a Microsoft.Application Elemzések SDK-ban: ApplicationInsightsApplicationIdProvider és DictionaryApplicationIdProvider.

Alkalmazás Elemzések ApplicationIdProvider

Ez a burkoló a Profil API-hoz készült. Ez szabályozza a kéréseket és a gyorsítótár eredményeit.

Ez a szolgáltató a Microsoft.Application telepítésekor hozzáadódik a konfigurációs fájlhoz Elemzések. DependencyCollector vagy Microsoft.Application Elemzések. Web.

Ez az osztály nem kötelező tulajdonságú ProfileQueryEndpoint. Alapértelmezés szerint a következőre https://dc.services.visualstudio.com/api/profiles/{0}/appIdvan állítva: . Ha proxyt kell konfigurálnia ehhez a konfigurációhoz, javasoljuk, hogy proxyként adja meg az alapcímet, és adja meg azokat "/api/profiles/{0}/appId". Az A {0} modul futásidőben, kérésenként a rendszerállapot-kulccsal helyettesíthető.

Példakonfiguráció alkalmazáson keresztül Elemzések.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élda a kódon keresztüli konfigurációra

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Ez a statikus szolgáltató a konfigurált rendszerállapotkulcs-/alkalmazásazonosító-párokra támaszkodik.

Ez az osztály rendelkezik a Defined tulajdonságával, amely Dictionary<string,string> a rendszerállapotkulcs-/alkalmazásazonosító-párok egyike.

Ez az osztály rendelkezik az opcionális tulajdonságkal Next, amely egy másik szolgáltató konfigurálására használható, ha olyan rendszerállapotkulcsot kér, amely nem létezik a konfigurációban.

Példakonfiguráció alkalmazáson keresztül Elemzések.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élda a kódon keresztüli konfigurációra

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

Pillanatkép-gyűjtemény konfigurálása ASP.NET alkalmazásokhoz

Pillanatkép-gyűjtemény konfigurálása ASP.NET alkalmazásokhoz.

Következő lépések

További információ az API-ról