Az Application Insights SDK konfigurálása az ApplicationInsights.config vagy .xml használatával

Az Application Elemzések .NET SDK számos NuGet-csomagból áll. A központi csomag biztosítja az API-t, amely telemetriát küld az Application Elemzések. A további csomagok telemetriai modulokat és inicializálókat biztosítanak az alkalmazásból és a környezetből származó telemetria 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, és néhányhoz paramétereket állíthat be.

A konfigurációs fájl neve ApplicationInsights.config vagy , az alkalmazás ApplicationInsights.xml típusától függően. A rendszer automatikusan hozzáadja a projekthez az SDK legtöbb verziójának telepítésekor. Alapértelmezés szerint a > Application Elemzések Telemetria hozzáadása alkalmazást támogató Visual Studio-sablonprojektek automatizált felhasználói élményének használata esetén a ApplicationInsights.config-fájl a projekt gyökérmappában jön létre, és a fordításkor a bin mappába lesz átmásolva. Egy IIS-kiszolgálón található Állapotmonitor is hozzáadja egy webalkalmazáshoz. A rendszer figyelmen kívül hagyja a konfigurációs fájlt, ha Azure-webhely vagy Azure-beli virtuális gép és virtuálisgép-méretezési készlet bővítményét használja.

Az SDK-t egy weblapon nem lehet ezzel egyenértékű fájllal vezérelni.

Ez a dokumentum ismerteti a konfigurációs fájlban látható szakaszokat, az SDK összetevőinek vezérlését, valamint az összetevőket betöltő NuGet-csomagokat.

Megjegyzés

ApplicationInsights.config és .xml utasítások nem vonatkoznak a .NET Core SDK. A .NET Core-alkalmazások konfigurálásához kövesse ezt az útmutatót.

Telemetriai modulok (ASP.NET)

Minden telemetriamodul egy adott adattípust gyűjt, és a központi API-t használja az adatok elküldéhez. A modulokat különböző NuGet-csomagok telepítik, amelyek a szükséges sorokat is hozzáadják .config fájlhoz.

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

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

A függőségek nyomon követése telemetriai adatokat gyűjt az alkalmazás adatbázisokkal, külső szolgáltatásokkal és adatbázisokkal kapcsolatos hívásairól. Ahhoz, hogy ez a modul működjön egy IIS-kiszolgálón, telepítenie kell a Állapotmonitor.

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

A függőségek automatikusan gyűjthetőek a kód ügynökalapú (kód nélküli) csatolás használatával való módosítása nélkül. Az Azure-webalkalmazásokban való használathoz engedélyezze az Application Elemzések bővítményt. Az Azure-beli virtuális gépen vagy Azure-beli virtuálisgép-méretezési készletben való használathoz engedélyezze az Alkalmazásfigyelés bővítményt a virtuális géphez és a virtuálisgép-méretezési készlethez.

Teljesítménygyűjtő

Rendszerteljesítmény-számlálókat, például processzor-, memória- és hálózati terhelést gyűjt az IIS-telepítésekből. Megadhatja, hogy mely számlálókat gyűjtse, beleértve a saját maga által beállított teljesítményszámlálókat is.

Application Elemzések Diagnostics telemetria

Az DiagnosticsTelemetryModule Alkalmazásjelentések a rendszer Elemzések jelentik a hibákat. Például ha a kód nem tud hozzáférni a teljesítményszámlálókhoz, vagy ha ITelemetryInitializer egy kivételt ad vissza. A modul által nyomon követhető nyomkövetési telemetria megjelenik a Diagnosztikai keresésben.

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

Fejlesztői mód

DeveloperModeWithDebuggerAttachedTelemetryModulekényszeríti az Elemzések, hogy azonnal küldjön adatokat, egyszerre egy telemetriai elemet, amikor egy hibakereső csatlakozik az TelemetryChannel alkalmazásfolyamathoz. Ez csökkenti azt az időt, amely a telemetriai adatok nyomon követik az alkalmazást, és amikor az megjelenik az Application Elemzések portalon. Ez 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 válaszidőt és a HTTP-kérések eredménykódját jelenti.

Kivételkövetés

ExceptionTrackingTelemetryModule A nyomon követi a nem kezelt kivételeket a webalkalmazásban. Lásd: Hibák és kivételek.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
  • Microsoft.ApplicationInsights.Web NuGet-csomag
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule – nyomon követi a nem észrevehetetlen feladat kivételeket
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule– nyomon követi a feldolgozói szerepkörök, Windows szolgáltatások és konzolalkalmazások nem kezelt kivételeit.
  • Alkalmazás Elemzések Windows Server NuGet-csomag.

EventSource-követés

EventSourceTelemetryModuleA segítségével konfigurálhatja, hogy az EventSource-események nyomkövetésként Elemzések applicationsource-nak. Az EventSource-események követésével kapcsolatos információkért lásd: Az EventSource-események használata.

ETW-eseménykövetés

EtwCollectorTelemetryModuleA lehetővé teszi, hogy az ETW-szolgáltatóktól származó eseményeket nyomkövetésként Elemzések alkalmazásnak. Az ETW-események követésével kapcsolatos információkért lásd: ETW-események használata.

Microsoft.ApplicationInsights

A Microsoft.ApplicationInsights csomag biztosítja az SDK alapvető API-ját. A többi telemetriamodul ezt használja, és saját telemetria meghatározására is használhatja.

  • Nincs bejegyzés a ApplicationInsights.config.
  • Microsoft.ApplicationInsights NuGet-csomag. Ha csak telepíti ezt a NuGet-et, .config létrejön egy új fájl.

Telemetria-csatorna

A telemetriai csatorna kezeli a telemetria pufferelését és az Application Elemzések továbbítását.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel A a webalkalmazások alapértelmezett csatornája. A memóriában pufferel adatokat, és újrapróbálkozási mechanizmusokat és helyi lemeztárolást alkalmaz a megbízhatóbb telemetria-kézbesítés érdekében.
  • Microsoft.ApplicationInsights.InMemoryChannel A egy egyszerűsített telemetriai csatorna, amelyet akkor használ a rendszer, ha nincs más csatorna konfigurálva.

Telemetria-inicializálók (ASP.NET)

A telemetria-inicializálók a telemetria minden elemének küldött környezeti tulajdonságokat is beállítják.

Saját inicializálókat is írhat a környezeti tulajdonságok beállításhoz.

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

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

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

  • AzureRoleEnvironmentTelemetryInitializer frissíti az összes telemetriai elem környezetének és tulajdonságait az Azure-beli futásidejű környezetből RoleName RoleInstance Device kinyert információkkal.

  • BuildInfoConfigComponentVersionTelemetryInitializer frissíti az összes telemetriai elem környezetének tulajdonságát az MS Build által előállított fájlból Version Component BuildInfo.config kinyert értékkel.

  • ClientIpHeaderTelemetryInitializer az összes telemetriai elem környezetének Ip Location updates tulajdonsága a kérés X-Forwarded-For HTTP-fejléce alapján.

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

    • Type A beállítása "PC"
    • Id A a webalkalmazást futtató számítógép tartománynevére van beállítva.
    • OemName A értéke a mezőből a WMI használatával Win32_ComputerSystem.Manufacturer kinyert érték.
    • Model A értéke a mezőből a WMI használatával Win32_ComputerSystem.Model kinyert érték.
    • NetworkType A értéke a értékből kinyert NetworkInterface értékre van állítva.
    • Language A a nevére van CurrentCulture állítva.
  • DomainNameRoleInstanceTelemetryInitializer frissíti az összes telemetriai elem környezetének tulajdonságát annak a számítógépnek a tartománynevével, ahol RoleInstance Device a webalkalmazás fut.

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

  • OperationIdTelemetryInitializer vagy frissíti az automatikusan generált kérések kezelése közben nyomonott összes telemetriai elem környezeti OperationCorrelationTelemetryInitializer Operation.Id RequestTelemetry.Id tulajdonságát.

  • SessionTelemetryInitializer frissíti az összes telemetriai elem környezetének tulajdonságát a felhasználó böngészőjében futó Id Session ApplicationInsights JavaScript-eszközkód által létrehozott cookie-ból kinyert ai_session értékkel.

  • SyntheticTelemetryInitializer vagy frissíti az összes olyan telemetriai elem , és környezettulajdonságait, amelyek nyomon vannak követve egy szintetikus forrásból, például egy rendelkezésre állási tesztből vagy keresőmotor-robotból származó SyntheticUserAgentTelemetryInitializer User Session Operation kérések kezelésekor. Alapértelmezés szerint a Metrikaböngésző nem jelenít meg szintetikus telemetriát.

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

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

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

A alkalmazásban futó .NET-Service Fabric a Microsoft.ApplicationInsights.ServiceFabric NuGet-csomagot is használhatja. Ez a csomag tartalmaz egy FabricTelemetryInitializer elemet, amely Service Fabric tulajdonságokat ad a telemetriai elemekhez. További információért tekintse meg GitHub NuGet-csomag által hozzáadott tulajdonságokat.

Telemetriai processzorok (ASP.NET)

A telemetriafeldolgozók szűrni és módosítani is tudnak minden telemetriai elemet, mielőtt azokat az SDK-ból a portálra küldeik.

Saját telemetriai processzorokat is írhat.

Adaptív mintavételezési telemetriafeldolgozó (2.0.0-beta3)

Ez e beállítás alapértelmezés szerint engedélyezve van. Ha az alkalmazás sok telemetriát küld, ez a processzor eltávolít néhányat.


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

A paraméter biztosítja azt a célt, amit az algoritmus megpróbál elérni. Az SDK minden példánya egymástól függetlenül működik, így ha a kiszolgáló több gépből áll, a rendszer ennek megfelelően megszorozza a tényleges telemetriamennyiséget.

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

Rögzített sebességetű mintavételezési telemetriafeldolgozó (2.0.0-beta1)

Emellett egy standard mintavételezési telemetriai feldolgozó is rendelkezésre áll (2.0.1-esrő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>

InstrumentationKey (Eszközkulcs)

Ez határozza meg azt az Application Elemzések erőforrást, amelyben az adatok megjelennek. Általában külön erőforrást hoz létre külön kulccsal az egyes alkalmazásokhoz.

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

A TelemetryClient összes példányának kulcsának beállítása, beleértve a standard telemetriai modulokat is. Ezt egy inicializálási módszerrel, például a global.aspx.cs fájlban, 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 csak egy adott eseménykészletet szeretne elküldeni egy másik erőforrásnak, beállíthatja egy adott TelemetryClient kulcsát:


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

Új kulcs lekért létrehozásához hozzon létre egy új erőforrást az Alkalmazás Elemzések portálon.

ApplicationId Provider

A 2.6.0-stól kezdődően érhető el

Ennek a szolgáltatónak az a célja, hogy alkalmazásazonosítót keressen egy eszközkulcs alapján. Az alkalmazásazonosítót a RequestTelemetry és a DependencyTelemetry tartalmazza, és a portálon a korreláció meghatározására használható.

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

Felület: IApplicationIdProvider

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

A Microsoft.ApplicationInsights sdk-ban két implementációt biztosítunk: ApplicationInsightsApplicationIdProvider és DictionaryApplicationIdProvider .

ApplicationInsightsApplicationIdProvider

Ez egy burkoló a Profile API körül. Ez fogja eltenni a kérelmeket és gyorsítótárazza az eredményeket.

Ez a szolgáltató a Microsoft.ApplicationInsights.DependencyCollector vagy a Microsoft.ApplicationInsights.Web telepítésekor lesz hozzáadva a konfigurációs fájlhoz

Ez az osztály egy opcionális tulajdonságot is ProfileQueryEndpoint rendelkezik. Alapértelmezés szerint ez a következőre van állítva: https://dc.services.visualstudio.com/api/profiles/{0}/appId . Ha proxyt kell konfigurálnia ehhez a konfigurációhoz, javasoljuk, hogy proxyval adja meg az alapcímet, és adja meg az "/api/profiles/ {0} /appId" adatokat. Vegye figyelembe, hogy a futásidőben a ' {0} helyettesítve kérésenként a Instrumentation Key rel.

Példa konfiguráció 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élda konfiguráció kódon keresztül:

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Ez egy statikus szolgáltató, amely a konfigurált eszközkulcs-/alkalmazásazonosító-párokat használja.

Ez az osztály rendelkezik egy tulajdonságával, amely egy Dictionary<,string> a instrumentation key to Application ID (Eszközkulcs és alkalmazásazonosító) Defined párok között.

Ez az osztály egy opcionális tulajdonságot is tartalmaz, amellyel konfigurálható egy másik szolgáltató, amikor olyan eszközkulcsot kérnek, amely nem létezik a Next konfigurációban.

Példa konfiguráció 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élda konfiguráció kódon keresztül:

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

Következő lépések

További információ az API-val kapcsolatban.