Application Insights API egyéni eseményekhez és metrikákhoz

Szúrjon be néhány sornyi kódot az alkalmazásba, hogy megtudja, mire valók a felhasználók, vagy segíthet diagnosztizálni a problémákat. Telemetriát küldhet eszköz- és asztali alkalmazásokból, webes ügyfelekről és webkiszolgálókról. Az Azure Application Elemzések alapvető telemetriai API-val egyéni eseményeket és metrikákat, valamint a standard telemetria saját verzióit küldheti el. Ez az API ugyanaz az API, mint a szabványos Application Elemzések adatgyűjtők használják.

API összefoglaló

A központi API minden platformon egységes, kivéve néhány változatot, például GetMetric a (csak .NET-et).

Metódus Alkalmazási cél
TrackPageView Oldalak, képernyők, panelek vagy űrlapok.
TrackEvent Felhasználói műveletek és egyéb események. A felhasználói viselkedés nyomon követésére vagy a teljesítmény figyelése.
GetMetric Nulla és többdimenziós metrikák, központilag konfigurált összesítés, csak C#
TrackMetric Teljesítménymérések, például az egyes eseményekhez nem kapcsolódó várólista-hosszak.
TrackException Naplózási kivételek a diagnosztikákhoz. Nyomon követhet, hogy hol fordulnak elő más eseményekhez képest, és megvizsgálhatja a veremkövetéseket.
TrackRequest A kiszolgálókérések gyakoriságának és időtartamának naplózása a teljesítményelemzéshez.
TrackTrace Erőforrás-diagnosztikai naplóüzenetek. Harmadik féltől származó naplókat is rögzíthet.
TrackDependency A külső összetevők hívási időtartamának és gyakoriságának naplózása, amelyektől az alkalmazás függ.

A legtöbb telemetriai híváshoz tulajdonságokat és metrikákat csatolhat.

Előkészületek

Ha még nincs hivatkozása az Application Elemzések SDK-hoz:

  • Adja hozzá az Application Elemzések SDK-t a projekthez:

  • Az eszköz vagy a webkiszolgáló kódjának a következőket kell tartalmaznia:

    C#:using Microsoft.ApplicationInsights;

    Visual Basic:Imports Microsoft.ApplicationInsights

    Java:import com.microsoft.applicationinsights.TelemetryClient;

    Node.js:var applicationInsights = require("applicationinsights");

TelemetryClient-példány lekért példánya

Szerezze be a egy TelemetryClient példányát (kivéve JavaScriptben weblapok esetén):

A ASP.NET Core alkalmazások és a nem HTTP/feldolgozó .NET/.NET Core-alkalmazások esetében javasoljuk, hogy szerezze be a egy példányát a függőséginjektálásos tárolóból a vonatkozó TelemetryClient dokumentációban leírtak szerint.

Ha az AzureFunctions v2+ vagy Azure WebJobs v3+ használatával használja, kövesse ezt a dokumentumot.

C#

private TelemetryClient telemetry = new TelemetryClient();

Ha ezt a módszert látja, az elavult üzenetekkel kapcsolatos további részletekért látogasson el a microsoft/ApplicationInsights-dotnet#1152 webhelyre.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

A TelemetryClient szál számára biztonságos.

A ASP.NET És Java-projektek esetében a bejövő HTTP-kérések automatikusan rögzítettek. Érdemes lehet további TelemetryClient-példányokat létrehozni az alkalmazás más modulja számára. Előfordulhat például, hogy a middleware osztályban egy TelemetryClient példány van az üzleti logikai események jelentéséhez. A gép azonosításához olyan tulajdonságokat állíthat be, mint a UserId és a DeviceId. Ez az információ a példány által küldött összes eseményhez csatolva van.

C#

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Java

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

A Node.js a használatával létrehozhat egy új példányt, de ez csak olyan forgatókönyvekhez ajánlott, amelyek az egyedülállótól elkülönített konfigurációt new applicationInsights.TelemetryClient(instrumentationKey?) defaultClient igényelnek.

TrackEvent (Nyomon követése)

Az Application Elemzések az egyéni esemény egy adatpont, amely megjeleníthető a Metrikaböngésző összesített számként és a Diagnosztikai keresésben egyéni előfordulásként. (Nem kapcsolódik az MVC-hez vagy más keretrendszer "eseményeihez".)

Szúrjon TrackEvent be hívásokat a kódba a különböző események megszámlálása során. Az, hogy a felhasználók milyen gyakran választják ki egy adott funkciót, milyen gyakran érnek el bizonyos célokat, vagy hogy milyen gyakran vétik bizonyos típusú hibákat.

Egy játékalkalmazásban például küldjön egy eseményt, amikor egy felhasználó megnyeri a játékot:

JavaScript

appInsights.trackEvent({name:"WinGame"});

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

telemetry.trackEvent({name: "WinGame"});

Egyéni események az Analyticsben

A telemetria az customEvents Application Elemzések Logs (Használati élmény) lap táblázatában érhető el. Az események a webhelyről, trackEvent(..) vagy a Click Analytics auto-collection beépülő modulból () is előfordulhatnak.

Ha mintavételezés van működésben, az itemCount tulajdonság egy 1-esnél nagyobb értéket mutat. Az itemCount==10 például azt jelenti, hogy a trackEvent() 10 hívása esetén a mintavételezési folyamat csak az egyiket továbbította. Az egyéni események helyes darabszámának lekért létrehozásához ezért olyan kódot kell használnia, mint a customEvents | summarize sum(itemCount) .

GetMetric

Ha meg szeretne ismerkedni a GetMetric() hívás hatékony használatával a .NET- és .NET Core-alkalmazások helyi, előre összesített metrikai rögzítéséhez, olvassa el a GetMetric dokumentációját.

TrackMetric (Nyomon követése)

Megjegyzés

A Microsoft.ApplicationInsights.TelemetryClient.TrackMetric nem a metrikák küldésének előnyben részesített módszere. A metrikákat mindig előre összesíteni kell egy adott időszakban, mielőtt elküldeik őket. A GetMetric(..) egyik túlterhelésével egy metrikaobjektumot kap az SDK előzetes összesítési képességeinek eléréséhez. Ha saját összesítés előtti logikát használ, a TrackMetric() metódussal elküldheti az eredményül kapott összesítéseket. Ha az alkalmazás minden alkalommal külön telemetriai elemet küld összesítés nélkül, valószínűleg van egy használati esete az esemény-telemetriához; lásd: TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Az Elemzések diagramon ábrázolhatja az adott eseményekhez nem csatolt metrikákat. Figyelheti például rendszeres időközönként az üzenetsor hosszát. A metrikák esetében az egyes mérések kevésbé érdekesek, mint a variációk és trendek, ezért hasznosak a statisztikai diagramok.

Ahhoz, hogy metrikákat küldjön az Application Elemzések, használhatja az TrackMetric(..) API-t. A metrikák elküldését kétféleképpen lehet:

  • Egyetlen érték. Minden alkalommal, amikor mérést végez az alkalmazásban, elküldi a megfelelő értéket az Application Elemzések. Tegyük fel például, hogy van egy metrika, amely leírja a tárolóban lévő elemek számát. Egy adott időszakban először három elemet kell a tárolóba helyeznie, majd el kell távolítania két elemet. Ennek megfelelően kétszer kell TrackMetric hívnia a-t: először át kell adnunk az 3 értéket, majd a -2 értéket. Az Elemzések mindkét értéket az Ön nevében tárolja.

  • Összesítés. A metrikákon végzett munka során minden mérés ritkán érdekes. Ehelyett fontos összefoglalni, hogy mi történt egy adott időszakban. Az ilyen összegzést összesítésnek nevezzük. A fenti példában az adott időszak összesített metrikaösszege , a metrikaértékek száma 1 pedig 2 . Az összesítési módszer használata esetén időszakonként csak egyszer kell meghívni, TrackMetric és el kell küldenie az összesített értékeket. Ez az ajánlott megközelítés, mivel jelentősen csökkentheti a költségeket és a teljesítménybeli többletterhelést azáltal, hogy kevesebb adatpontot küld az Application Elemzések, miközben továbbra is gyűjti az összes releváns információt.

Példák

Egyetlen érték

Egyetlen metrikaérték küldése:

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

C#

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Value = 42.3;
telemetryClient.TrackMetric(sample);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

telemetry.trackMetric({name: "queueLength", value: 42.0});

Egyéni metrikák az Elemzésben

A telemetria az customMetrics Application Elemzések Analytics táblázatában érhető el. Minden sor egy-egy hívását jelöli trackMetric(..) az alkalmazásban.

  • valueSum – Ez a mérések összege. A átlagos érték lekért értékével oszd meg a valueCount értéket.
  • valueCount – A hívásban összesített mérések trackMetric(..) száma.

Lapnézetek

Egy eszköz- vagy weblapalkalmazásban a rendszer alapértelmezés szerint lapnézeti telemetriát küld az egyes képernyők vagy oldalak betöltésekor. Ezt azonban módosíthatja az oldalnézetek további vagy eltérő időpontokban való nyomon követéséhez. Például egy lapokat vagy paneleket megjelenítő alkalmazásban érdemes lehet nyomon követni az oldalakat, amikor a felhasználó új panelt nyit meg.

A felhasználói és munkamenet-adatokat a rendszer tulajdonságokként és lapnézetekként küldi el, így a felhasználói és munkamenet-diagramok akkor is életre kelnek, ha lapnézeti telemetria van.

Egyéni lapnézetek

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Ha több lap található a különböző HTML-oldalakon, az URL-címet is megadhatja:

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

Időzítés lapnézetek

Alapértelmezés szerint az Oldal nézet betöltési idejeként jelentett idő mérése a böngésző kérésének elküldési ideje alapján történik, egészen a böngésző oldalbetöltési eseményének behívásáig.

Ehelyett a következőt használhatja:

  • Állítson be egy explicit időtartamot a trackPageView hívásban: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds); .
  • Használja az oldalnézet időzítési hívásait és startTrackPage stopTrackPage a et.

JavaScript

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

Az első paraméterként használt név az indítási és leállítási hívásokat társítja. Az alapértelmezett érték az aktuális oldal neve.

Az itt látható oldalbetöltési időtartamok Metrikaböngésző az indítási és leállítási hívások közötti időközből származnak. Önn a ténylegesen időintervallumon belül van megszabadva.

Laptelemetelemetia az Elemzésben

Az Elemzésben két tábla a böngészőműveletből származó adatokat mutatja:

  • A pageViews táblázat az URL-címmel és az oldal címével kapcsolatos adatokat tartalmaz
  • A tábla az ügyfél teljesítményével kapcsolatos adatokat tartalmaz, például a bejövő adatok browserTimings feldolgozásához szükséges időt

A böngésző által a különböző oldalak feldolgozásához szükséges idő megmutatja:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

A különböző böngészők népszerűségeit a következő módon fedezheti fel:

pageViews
| summarize count() by client_Browser

Ha lapnézeteket szeretne társítani AJAX-hívásokhoz, csatlakozzon a függőségekkel:

pageViews
| join (dependencies) on operation_Id 

TrackRequest (TrackRequest)

A kiszolgálói SDK a TrackRequest használatával naplóz HTTP-kéréseket.

Akkor is meg is hívhatja, ha olyan környezetben szeretné szimulálni a kéréseket, ahol nem fut a webszolgáltatás modulja.

A kérelem-telemetria elküldését azonban az ajánlott módszer az, ha a kérés műveleti környezetként működik.

Műveleti környezet

A telemetriaelemeket össze lehet korrelálni, ha a műveleti környezethez társítja őket. A szabványos kéréskövető modul ezt a HTTP-kérés feldolgozása során küldött kivételek és egyéb események esetén teszi meg. A Search and Analytics (Keresés és analitika)szolgáltatásban a kérelemhez társított események könnyedén megtalálhatók annak műveleti azonosítójával.

A korrelációval kapcsolatos további részletekért Elemzések application Elemzések telemetriai korrelációt.

A telemetria manuális nyomon követésekor a legegyszerűbb módszer a telemetria-korreláció biztosítására a következő minta használatával:

C#

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

A műveletkörnyezet beállítása mellett a létrehoz egy ön által megadott típusú StartOperation telemetriaelemet. Elküldi a telemetriai elemet, amikor eldobja a műveletet, vagy ha explicit módon hívja meg a StopOperation elemet. Ha a telemetriatípust használja, annak időtartama az indítás és a leállítás közötti időintervallumra RequestTelemetry van állítva.

A művelet hatókörében jelentett telemetriai elemek az ilyen művelet "gyermek" elemeivé válnak. A műveleti környezetek beágyazhatóak.

A Keresésben a műveleti környezet a Kapcsolódó elemek lista létrehozására használható:

Kapcsolódó elemek

Az egyéni műveletek nyomon követésével kapcsolatos további információkért lásd: Egyéni műveletek nyomon követése Elemzések .NET SDK-val.

Kérések az Analyticsben

Az Application Elemzések Analyticsbena kérések a táblázatban adatokat mutatjak. requests

Ha mintavételezés van működésben, az itemCount tulajdonság egy 1-esnél nagyobb értéket fog mutatni. Az itemCount==10 például azt jelenti, hogy a trackRequest() 10 hívása esetén a mintavételezési folyamat csak az egyiket továbbította. A kérések helyes darabszámának és a kérelemnevek alapján szegmentált átlagos időtartamnak a lekérése a következő kóddal kérhető le:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException (TrackException)

Kivételek küldése az Application Elemzések:

A jelentések tartalmazzák a veremkövetéseket.

C#

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Java

try {
    ...
} catch (Exception ex) {
    telemetry.trackException(ex);
}

JavaScript

try
{
    ...
}
catch (ex)
{
    appInsights.trackException({exception: ex});
}

Node.js

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

Az SDK-k számos kivételt automatikusan elfognak, így nem mindig kell explicit módon hívnia a TrackException kivételt.

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

Kivételek az Elemzésben

Az Application Elemzések Analyticsbena kivételek a táblában adatokat exceptions mutatják be.

Ha mintavételezés van, a itemCount tulajdonság egy 1-esnél nagyobb értéket mutat. Az itemCount==10 például azt jelenti, hogy a trackException() 10 hívása esetén a mintavételezési folyamat csak az egyiket továbbította. A kivételek megfelelő számát a kivétel típusa szerint szegmentálva a következő kóddal használhatja:

exceptions
| summarize sum(itemCount) by type

A fontos vereminformációk nagy része már külön változókba van kinyerve, de a struktúra szét is bontható, így details több információhoz jut. Mivel ez a struktúra dinamikus, az eredményt a várt típusra kell átemelni. Például:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Ha kivételeket szeretne társítani a kapcsolódó kérelmekhez, használjon illesztéseket:

exceptions
| join (requests) on operation_Id

TrackTrace

A TrackTrace használatával "útkövető út" küldve segítséget a problémák diagnosztizálásához az Elemzések. Diagnosztikai adatok adattömbit is elküldheti, és megvizsgálhatja őket a Diagnosztikai keresésben.

A .NET-naplóadapterek ezen API használatával küldenek külső gyártótól származó naplókat a portálra.

A Java-Elemzések Java-ügynök automatikusan gyűjti és elküldi a naplókat a portálra.

C#

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Java

telemetry.trackTrace(message, SeverityLevel.Warning, properties);

Node.js

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

Ügyfél-/böngészőoldali JavaScript

trackTrace({
    message: string, 
    properties?: {[string]:string}, 
    severityLevel?: SeverityLevel
})

Diagnosztikai esemény naplózása, például egy metódus bevitele vagy elhagyása.

Paraméter Leírás
message Diagnosztikai adatok. A névnél sokkal hosszabb lehet.
properties Sztring–sztring leképezés: A kivételek szűréséhez használt további adatok a portálon. Az alapértelmezett érték az üres.
severityLevel Támogatott értékek: SeverityLevel.ts

Kereshet az üzenet tartalmában, de (a tulajdonságértékekkel ellentétben) nem szűrhet rá.

A méretkorlátja message sokkal magasabb, mint a tulajdonságokra vonatkozó korlát. A TrackTrace előnye, hogy viszonylag hosszú adatokat is beletehet az üzenetbe. A POST-adatokat például itt kódolhatja.

Emellett súlyossági szintet is hozzáadhat az üzenethez. Más telemetriákhoz hasonló módon tulajdonságértékeket is hozzáadhat, amelyek segítenek a különböző nyomkövetési halmazok szűrésében vagy keresésében. Például:

C#

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Java

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

A Keresésrészen ezután egyszerűen kiszűrheti az adott adatbázishoz kapcsolódó, adott súlyossági szinthez kapcsolódó összes üzenetet.

Nyomkövetések az elemzésben

Az Application Elemzések Analyticsben aTrackTrace hívásai nak kell mutatniuk a traces táblában.

Ha mintavételezés van, az itemCount tulajdonság egy 1-esnél nagyobb értéket mutat. Az itemCount==10 például azt jelenti, hogy a 10 hívása esetén a mintavételezési folyamat csak az egyiket trackTrace() továbbította. A nyomkövetési hívások helyes darabszámának lehívását a következő kód használatával kell lehívni: traces | summarize sum(itemCount) .

TrackDependency

A TrackDependency hívás használatával nyomon követheti a külső kódrészek hívásának válaszideje és sikerességi aránya. Az eredmények a portál függőségi diagramjaiban jelennek meg. Az alábbi kódrészletet minden függőségi híváshoz hozzá kell adni.

Megjegyzés

A .NET és a .NET Core esetén használhatja a (extension) metódust is, amely kitölti a korrelációhoz szükséges tulajdonságokat és néhány más tulajdonságot, például a kezdési időt és az időtartamot, így nem kell egyéni időzítőt létrehoznia, ahogyan az alábbi TelemetryClient.StartOperation DependencyTelemetry példákban látható. További információért tekintse meg a kimenő függőségek nyomon követésével kapcsolatos cikk szakaszát.

C#

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex) 
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

Java

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.js

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Ne feledje, hogy a kiszolgálói SDK-k tartalmaznak egy függőségi modult, amely automatikusan felderít és nyomon követ bizonyos függőségi hívásokat, például adatbázisokat és REST API-kat. A modul megfelelő munkához telepítenie kell egy ügynököt a kiszolgálóra.

A Javában számos függőségi hívás automatikusan nyomon követhető a Java Elemzések használatával.

Ezt a hívást akkor használja, ha olyan hívásokat szeretne nyomon követni, amelyek az automatikus nyomon követést nem érik el.

A szabványos függőségkövetési modul C# környezetben való kikapcsolására szerkessze aApplicationInsights.config és törölje a DependencyCollector.DependencyTrackingTelemetryModule hivatkozását. Javával kapcsolatos információkért lásd: Adott, automatikusan gyűjtött telemetria mellőzése.

Függőségek az elemzésben

Az Application Elemzések Analyticsbena trackDependency hívások adatokat mutatja a dependencies táblában.

Ha mintavételezés van, az itemCount tulajdonság egy 1-esnél nagyobb értéket mutat. Az itemCount==10 például azt jelenti, hogy a trackDependency() 10 hívása esetén a mintavételezési folyamat csak az egyiket továbbította. A célösszetevők szerint szegmentált függőségek helyes darabszámának le eléréséhez használja a következő kódot:

dependencies
| summarize sum(itemCount) by target

Ha függőségeket szeretne társítani a kapcsolódó kérésekkel, használjon illesztéseket:

dependencies
| join (requests) on operation_Id

Adatok kiürítés

Az SDK általában rögzített időközönként (általában 30 mp) vagy amikor a puffer megtelik (általában 500 elem). Bizonyos esetekben azonban érdemes lehet kiüríteni a puffert – például ha az SDK-t egy leállított alkalmazásban használja.

C#

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

A függvény aszinkron a kiszolgálói telemetriai csatornához.

Ideális esetben a flush() metódust kell használni az alkalmazás leállítási tevékenységében.

Hitelesített felhasználók

Egy webalkalmazásban a felhasználókat (alapértelmezés szerint) a cookie-k azonosítják. Előfordulhat, hogy egy felhasználó egynél több alkalommal is meg lesz számolva, ha egy másik gépről vagy böngészőből fér hozzá az alkalmazáshoz, vagy törli a cookie-kat.

Ha a felhasználók bejelentkeznek az alkalmazásba, pontosabban számolhat a hitelesített felhasználói azonosító böngészőkódban való beállításával:

JavaScript

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

Egy ASP.NET MVC-alkalmazásban, például:

Borotva

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

Nem szükséges a felhasználó tényleges bejelentkezési nevét használni. Csak az adott felhasználó egyedi azonosítójának kell lennie. Nem tartalmazhat szóközöket vagy ,;=| karaktereket.

A felhasználói azonosító egy munkamenet-cookie-ban is be van állítva, és el lesz küldve a kiszolgálónak. Ha a kiszolgálói SDK telepítve van, a hitelesített felhasználói azonosító az ügyfél- és kiszolgáló-telemetria környezeti tulajdonságainak részeként lesz elküldve. Ezután szűrhet rá, és rákereshet.

Ha az alkalmazás fiókokba csoportosja a felhasználókat, a fiók azonosítóját is meg lehet adni (ugyanazokkal a karakterkorlátozásokkal).

appInsights.setAuthenticatedUserContext(validatedId, accountId);

A Metrikaböngészőlétrehozhat egy diagramot, amely a Users (Felhasználók) , a Authenticated (Hitelesített) és a User accounts (Felhasználói fiókok) adatokat számlálja meg.

Adott felhasználónevekkel és fiókokkal rendelkező ügyféladatpontokat is kereshet.

Megjegyzés

Az .NET Core SDK ApplicationInsightsServiceOptions osztályának EnableAuthenticationTrackingJavaScript tulajdonsága leegyszerűsíti a felhasználónevet az Application Elemzések JavaScript SDK által küldött minden nyomkövetés hitelesítési azonosítójaként való be injektálásához szükséges JavaScript-konfigurációban. Ha ez a tulajdonság true (igaz) értékre van állítva, a rendszer kinyomtatja a felhasználó felhasználónevét a ASP.NET Core-ben az ügyféloldali telemetriávalegyütt, így manuális hozzáadásra már nincs szükség, mivel az SDK már injektálta appInsights.setAuthenticatedUserContext ASP.NET Core. A hitelesítési azonosítót arra a kiszolgálóra is elküldi a rendszer, ahol a .NET Core SDK azonosítja azt, és ezt használja bármely kiszolgálóoldali telemetriához, a JavaScript API-referenciában leírtak szerint. Az olyan JavaScript-alkalmazások esetében azonban, amelyek nem ugyanúgy működnek, mint az ASP.NET Core MVC (például az SPA-webalkalmazások), manuálisan kell appInsights.setAuthenticatedUserContext hozzáadnia.

Adatok szűrése, keresése és szegmentálása tulajdonságok használatával

Tulajdonságokat és méréseket csatolhat az eseményekhez (valamint metrikákhoz, lapnézethez, kivételekhez és egyéb telemetriai adatokhoz).

A tulajdonságok sztringértékek, amelyek a telemetria használati jelentésekben való szűrésére használhatók. Ha például az alkalmazás több játékkal is rendelkezik, minden eseményhez csatolhatja a játék nevét, így láthatja, hogy mely játékok népszerűbbek.

A sztring hossza legfeljebb 8192 lehet. (Ha nagy mennyiségű adatot szeretne küldeni, használja a TrackTrace üzenetparaméterét.)

A metrikák grafikusan ábrázolható numerikus értékek. Előfordulhat például, hogy szeretné látni, hogy fokozatosan növekednek-e a játékosok által elért pontszámok. A gráfok szegmentálhatóak az eseményhez küldött tulajdonságok alapján, így különböző játékokhoz külön vagy halmozott gráfokat kaphat.

Ahhoz, hogy a metrikaértékek helyesen jelennek meg, 0-ásnál nagyobbnak vagy egyenlőnek kell lennie.

A használható tulajdonságok, tulajdonságértékek és metrikák száma bizonyos korlátokkal rendelkezik.

JavaScript

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

C#

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

Node.js

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

' Send the event:
telemetry.TrackEvent("WinGame", properties, metrics)

Java

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

Megjegyzés

A személyes azonosításra alkalmas adatokat ne naplózd a tulajdonságokban.

Tulajdonságok és metrikák beállításának alternatív módja

Ha kényelmesebb, egy esemény paramétereit egy külön objektumban gyűjtheti össze:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Figyelmeztetés

Ne használja újra ugyanazt a telemetriaielem-példányt (ebben event a példában) a Track*() többszöri hívására. Ez a telemetria helytelen konfigurációval való elküldését okozhatja.

Egyéni mérések és tulajdonságok az Elemzésben

Az Elemzésbenaz egyéni metrikák és tulajdonságok az egyes telemetriarekordok customMeasurements és customDimensions attribútumai között adatokat tartalmaznak.

Ha például hozzáadott egy "game" nevű tulajdonságot a kérelem-telemetriában, ez a lekérdezés megszámolja a "game" különböző értékeinek előfordulását, és az egyéni "score" metrika átlagát mutatja:

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Figyelje meg az alábbiakat:

  • Amikor kinyer egy értéket a customDimensions vagy a customMeasurements JSON-fájlból, az dinamikus típussal rendelkezik, ezért a vagy a típust kell tostring todouble átírni.
  • A mintavételezési lehetőségének figyelembevételeként használja a et, ne sum(itemCount) a count() következőt: .

Időzítési események

Előfordulhat, hogy egy művelet végrehajtásához szükséges időt szeretné ábrázolni. Előfordulhat például, hogy tudni szeretné, mennyi ideig tart a felhasználók számára, hogy döntéseket hozzanak egy játékban. Ehhez használhatja a measurement paramétert.

C#

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Java

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

// Send the event
telemetry.trackEvent("SignalProcessed", properties, metrics);

Az egyéni telemetria alapértelmezett tulajdonságai

Ha alapértelmezett tulajdonságértékeket szeretne beállítani az Ön által írt egyes egyéni eseményekhez, beállíthatja őket egy TelemetryClient példányban. Ezek az ügyféltől küldött összes telemetriaelemhez csatolva vannak.

C#

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame");

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

Java

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.js

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

Az egyes telemetriai hívások felülbírálhatják a tulajdonságszótáraikban található alapértelmezett értékeket.

JavaScript-alapú webes ügyfelek esetében használjon JavaScript telemetria-inicializálókat.

Ha tulajdonságokat szeretne hozzáadni az összes telemetriai adathoz, beleértve a standard gyűjtési modulokból származó adatokat is, implementálja a következőt: ITelemetryInitializer.

Mintavételezés, szűrés és telemetria feldolgozása

Írhat olyan kódot, amely feldolgozja a telemetriát, mielőtt az SDK-ból küldenék. A feldolgozás magában foglalja a szabványos telemetriai modulokból küldött adatokat, például a HTTP-kérések gyűjtését és a függőségek gyűjtését.

Adjon tulajdonságokat a telemetriának a ITelemetryInitializer megvalósításával. Hozzáadhat például verziószámokat vagy más tulajdonságokból kiszámított értékeket.

A szűrés a használatával módosíthatja vagy elvetheti a telemetriát, mielőtt az SDK-ból küldeik ITelemetryProcessor el. Ön szabályozhatja az elküldött vagy elvetett adatokat, de figyelembe kell vennie a metrikákra gyakorolt hatást. Attól függően, hogyan veti el az elemeket, előfordulhat, hogy nem tud navigálni a kapcsolódó elemek között.

A mintavételezés egy csomagolt megoldás, amely csökkenti az alkalmazásból a portálra küldött adatok mennyiségét. Ezt a megjelenített metrikák befolyásolása nélkül teszi meg. Ezt anélkül teszi meg, hogy befolyásolná a problémák diagnosztizálási képességét a kapcsolódó elemek, például a kivételek, a kérések és a lapnézetek közötti navigálással.

További információk.

Telemetria letiltása

A telemetria gyűjtésének és átvitelének dinamikus leállítása és átvitele:

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

A kiválasztott standard gyűjtők – például teljesítményszámlálók, HTTP-kérések vagy függőségek – letiltásához törölje vagy megjegyzésként fűzje hozzá a megfelelő sorokat a ApplicationInsights.config. Ezt például akkor használhatja, ha saját TrackRequest-adatokat szeretne küldeni.

Node.js

telemetry.config.disableAppInsights = true;

A kiválasztott standard gyűjtők – például teljesítményszámlálók, HTTP-kérések vagy függőségek – letiltásához az inicializáláskor láncolhatja a konfigurációs metódusokat az SDK inicializálási kódhoz:

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Az inicializálás után ezeknek a gyűjtőknek a letiltásához használja a Configuration objektumot: applicationInsights.Configuration.setAutoCollectRequests(false)

Fejlesztői mód

A hibakeresés során hasznos lehet a telemetria folyamaton keresztüli gyorsítása, hogy azonnal láthatóak legyen az eredmények. Emellett további üzeneteket is kap, amelyek segítenek nyomon követni a telemetriával kapcsolatos problémákat. Éles környezetben kapcsolja ki, mert lelassíthatja az alkalmazást.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

A Node.js a fejlesztői módot úgy engedélyezheti, hogy engedélyezi a belső naplózást a és a beállításnál a 0 értéken, így a telemetria az gyűjtés után a lehető leghamarabb el lesz setInternalLogging maxBatchSize küldve.

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

A kiválasztott egyéni telemetria eszközkulcsának beállítása

C#

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Dinamikus eszközkulcs

A fejlesztési, tesztelési és éles környezetből származó telemetria vegyes használatának elkerülése érdekében külön Application Elemzések-erőforrásokat hozhat létre, és a környezettől függően módosíthatja a kulcsokat.

Ahelyett, hogy leküldi a rendszerkonfigurációs kulcsot a konfigurációs fájlból, beállíthatja azt a kódban. Állítsa be a kulcsot egy inicializálási módszerben, például a global.aspx.cs fájlban egy ASP.NET szolgáltatásban:

C#

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

JavaScript

appInsights.config.instrumentationKey = myKey;

A weblapok használata során érdemes lehet a webkiszolgáló állapotából beállítani, nem pedig a szkriptbe való kódolást. Például egy webalkalmazásban létrehozott ASP.NET:

JavaScript a Razorben

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:  
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...
    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

A TelemetryClient rendelkezik egy Context (Környezet) tulajdonsággal, amely a küldött értékeket és az összes telemetriai adatot tartalmazza. Ezeket általában a standard telemetriai modulok állítják be, de ön is beállíthatja őket. Például:

telemetry.Context.Operation.Name = "MyOperationName";

Ha ezen értékek bármelyikét saját maga adja meg, érdemes lehet eltávolítani a megfelelő sort aApplicationInsights.config-ból, hogy az értékek és a standard értékek ne tévesztendők össze.

  • Összetevő: Az alkalmazás és annak verziója.
  • Eszköz: Az alkalmazást futtató eszköz adatai. (A webalkalmazásokban ez az a kiszolgáló vagy ügyféleszköz, amelyről a telemetria küldve van.)
  • InstrumentationKey: Az Elemzések az Azure-ban, ahol a telemetria megjelenik. Általában az egyik ApplicationInsights.config.
  • Hely: Az eszköz földrajzi helye.
  • Művelet: A webalkalmazásokban az aktuális HTTP-kérés. Más alkalmazástípusokban beállíthatja, hogy az események csoportosítva vannak.
    • ID: Olyan generált érték, amely különböző eseményeket korrelál, így amikor megvizsgál egy eseményt a Diagnosztikai keresésben, megkeresheti a kapcsolódó elemeket.
    • Név: Egy azonosító, általában a HTTP-kérés URL-címe.
    • SyntheticSource: Ha nem null vagy üres, akkor egy sztring, amely azt jelzi, hogy a kérés forrása robotként vagy webes tesztként lett azonosítva. Alapértelmezés szerint ki van zárva a számításaiból a Metrikaböngésző.
  • Munkamenet: A felhasználó munkamenete. Az azonosító egy generált értékre van állítva, amely akkor változik meg, ha a felhasználó már egy ideje nem aktív.
  • Felhasználó: Felhasználói adatok.

Korlátok

A mérőszámok és események másodpercenkénti száma korlátozott a rendszerállapot-kulcs alapján. A korlátozások a választott díjszabási csomagtól függően változnak.

Erőforrás Alapértelmezett korlát Megjegyzés
Napi teljes adatmennyiség 100 GB Egy korlát beállításával csökkenthető az adatmennyiség. Ha több adatra van szüksége, növelheti a portálon megjelenő korlátot, amely akár 1 000 GB is lehet. A 1 000 GB-nál nagyobb kapacitások esetében küldjön e-mailt a címre AIDataCap@microsoft.com .
Throttling 32 000 esemény/másodperc A korlát megállapítása egy percnyi mérés alapján történik.
Adatmegőrzési naplók 30-730 nap Ez az erőforrás naplókhozhasználható.
Adatmegőrzési metrikák 90 nap Ez az erőforrás a Metrikaböngésző.
Többlépéses rendelkezésre állási teszt a részletes eredmények megőrzésével 90 nap Ez az erőforrás minden lépésről részletes eredményeket biztosít.
Telemetria maximális mérete 64 kB
Telemetria elemek maximális száma kötegben 64 K
Tulajdonság- és metrikanév hossza 150 Lásd: sémák beírása.
Tulajdonságérték-sztring hossza 8,192 Lásd: sémák beírása.
Nyomkövetési és kivételüzenet hossza 32 768 Lásd: sémák beírása.
Rendelkezésre állási tesztek száma alkalmazásonként 100
Profiler adatmegőrzés 5 nap
Profiler -adat elküldve naponta 10 GB

További információt az Application Insights árait és kvótáit ismertető cikkben talál.

Az adatátviteli sebességkorlát elkerüléséhez használjon mintavételezést.

Az adatmegőrzés időtartamának meghatározásához lásd: Adatmegőrzés és adatvédelem.

Referencia-dokumentumok

SDK-kód

Kérdések

  • Milyen kivételeket Track_() a hívások?

    Nincsenek. Ezeket nem kell try-catch záradékokba csomagolni. Ha az SDK problémába ütközik, naplóz üzeneteket a hibakeresési konzol kimenetében, és ha az üzenetek áthaladnak a diagnosztikai keresésen.

  • Van olyan REST API, amely lekérte az adatokat a portálról?

    Igen, az adatelérési API. Az adatok kinyerésének egyéb módjai közé tartozik az Elemzésből a Power BI és a folyamatos exportálás.

Következő lépések