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

Szúrjon be néhány sornyi kódot az alkalmazásba, hogy megtudja, mit csinálnak vele a felhasználók, vagy segítsen a problémák diagnosztizálásában. Telemetriát küldhet eszköz- és asztali alkalmazásokból, webügyfelekből és webkiszolgálókról. Az Application Insights alapvető telemetriai API-val egyéni eseményeket és metrikákat küldhet, valamint a standard telemetriai adatok saját verzióit is elküldheti. Ez az API ugyanaz az API, amelyet a standard Application Insights-adatgyűjtők használnak.

Megjegyzés

2025. március 31-én megszűnik az eszközkulcsalapú betöltés támogatása. A rendszerállapotkulcs-betöltés 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 sztringekre az új képességek kihasználásához.

API összefoglaló

A core API minden platformon egységes, néhány változaton kívül, például GetMetric (csak.NET).

Metódus Alkalmazási cél
TrackPageView Lapok, 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 monitorozására szolgál.
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 üzenetsor hossza, amelyek nem kapcsolódnak adott eseményekhez.
TrackException Kivételek naplózása a diagnózishoz. Nyomon követheti, hogy hol fordulnak elő más eseményekhez képest, és vizsgálja meg a verem-nyomkövetéseket.
TrackRequest A kiszolgálói kérelmek gyakoriságának és időtartamának naplózása a teljesítményelemzéshez.
TrackTrace Erőforrás-diagnosztikai naplóüzenetek. Külső naplókat is rögzíthet.
TrackDependency Az alkalmazás által függő külső összetevőkre irányuló hívások időtartamának és gyakoriságának naplózása.

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

Előkészületek

Ha még nem rendelkezik referenciával az Application Insights SDK-val kapcsolatban:

  • Adja hozzá az Application Insights SDK-t a projekthez:

  • Az eszköz vagy a webkiszolgáló kódjában adja meg a következőket:

    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érése

Példány lekérése TelemetryClient (kivéve a JavaScriptet a weblapokon):

A .NET/.NET Core-alkalmazásokhoz ASP.NET Core és nem HTTP/Worker típusú alkalmazások esetén a függőséginjektáló tárolóból szerezhet be egy példányt TelemetryClient a vonatkozó dokumentációjukban leírtak szerint.

Ha Azure Functions v2+ vagy Azure WebJobs v3+ verziót használja, tekintse meg a monitorozási Azure Functions című témakört.

C#

private TelemetryClient telemetry = new TelemetryClient();

Ha egy üzenet jelzi, hogy ez a módszer elavult, további információt a microsoft/ApplicationInsights-dotnet#1152 című témakörben talál.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient a szál biztonságos.

ASP.NET- és Java-projektek esetén a rendszer automatikusan rögzíti a bejövő HTTP-kéréseket. Előfordulhat, hogy további példányokat TelemetryClient szeretne létrehozni az alkalmazás más moduljaihoz. Előfordulhat például, hogy a köztes szoftverosztályban van egy TelemetryClient példány az üzleti logikai események jelentéséhez. A gép azonosításához beállíthat például UserId és DeviceId tulajdonságokkal. Ezek az információk a példány által küldött összes eseményhez csatolva vannak.

C#

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

Java

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

Node.js projektekben new applicationInsights.TelemetryClient(instrumentationKey?) létrehozhat egy új példányt. Ezt a megközelítést csak azokhoz a forgatókönyvekhez ajánljuk, amelyek elkülönített konfigurációt igényelnek a singletontól defaultClient.

TrackEvent

Az Application Insightsban az egyéni esemény egy adatpont, amelyet a Metrics Explorerben összesített számként, a Diagnosztikai keresésben pedig egyedi előfordulásként jeleníthet meg. (Nem kapcsolódik az MVC-hez vagy más keretrendszer "eseményeihez".)

A különböző események megszámlálásához szúrjon be TrackEvent hívásokat a kódba. Például érdemes lehet nyomon követni, hogy a felhasználók milyen gyakran választanak ki egy adott funkciót. Vagy érdemes lehet tudni, hogy milyen gyakran érnek el bizonyos célokat, vagy hogy bizonyos típusú hibákat.

Egy játékalkalmazásban például minden alkalommal küldjön eseményt, amikor egy felhasználó nyeri 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 a Log Analyticsben

A telemetria az customEventsApplication Insights-naplók lap táblázatában vagy a használati felületen érhető el. Az események származhatnak, vagy a Click Analytics automatikus gyűjtemény beépülő modulbóltrackEvent(..) származhatnak.

Ha a mintavételezés folyamatban van, a itemCount tulajdonság értéke nagyobb, mint 1. Például azt jelenti, itemCount==10 hogy a 10 hívás trackEvent()közül a mintavételezési folyamat csak az egyiket továbbította. Az egyéni események megfelelő számának lekéréséhez használjon olyan kódot, mint a customEvents | summarize sum(itemCount).

Megjegyzés

Az itemCount minimális értéke egy; maga a rekord egy bejegyzést jelöl.

GetMetric

Ha meg szeretné tudni, hogyan használhatja hatékonyan a hívást a GetMetric() .NET- és .NET Core-alkalmazások helyileg előre összesített metrikáinak rögzítésére, olvassa el az Egyéni metrikák gyűjtése a .NET-ben és a .NET Core-ban című témakört.

TrackMetric

Megjegyzés

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric nem a metrikák küldéséhez előnyben részesített módszer. A metrikákat mindig előre összesíteni kell egy adott időszakban, mielőtt elküldené őket. Használja az GetMetric(..) egyik túlterhelést egy metrikaobjektum lekéréséhez az SDK előzetes összesítési képességeinek eléréséhez.

Ha saját összesítés előtti logikát implementál, a TrackMetric() metódussal elküldheti az eredményül kapott összesítéseket. Ha az alkalmazásnak minden alkalommal külön telemetriai elemet kell küldenie összesítés nélkül, akkor valószínűleg van használati esete az eseménytelemetria esetében. Lásd: TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Az Application Insights képes olyan metrikákat ábrázolni, amelyek nincsenek adott eseményekhez csatolva. Például rendszeres időközönként monitorozhat egy üzenetsor hosszát. A metrikák esetében az egyes mérések kevésbé érdekesek, mint a variációk és trendek, így a statisztikai diagramok hasznosak.

Ha metrikákat szeretne küldeni az Application Insightsnak, használhatja az TrackMetric(..) API-t. A metrikák küldésének két módja van:

  • Egyetlen érték. Minden alkalommal, amikor mérést végez az alkalmazásban, elküldi a megfelelő értéket az Application Insightsnak.

    Tegyük fel például, hogy rendelkezik egy metrika használatával, amely a tárolóban lévő elemek számát írja le. Egy adott időszakban először három elemet helyez a tárolóba, majd eltávolít két elemet. Ennek megfelelően kétszer hívna TrackMetric . Először adja át az értéket 3 , majd adja át az értéket -2. Az Application Insights mindkét értéket tárolja.

  • Összesítés. Ha metrikákkal dolgozik, minden mérést ritkán érdemes figyelembe venni. Ehelyett fontos az adott időszakban történtek összegzése. Az ilyen összegzést aggregációnak nevezzük.

    Az előző példában az adott időszakra 1 vonatkozó összesített metrikaösszeg, a metrikaértékek száma pedig 2. Az aggregációs megközelítés használatakor időszakonként csak egyszer hív meg TrackMetric , és elküldi az összesített értékeket. Ezt a módszert azért javasoljuk, mert 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 Insightsnak, miközben továbbra is összegyűjti az összes releváns információt.

Példák egyértékű értékekre

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

JavaScript

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

C#

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

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

Egyéni metrikák a Log Analyticsben

A telemetria az customMetricsApplication Insights Analytics táblájában érhető el. Minden sor egy hívásnak trackMetric(..) felel meg az alkalmazásban.

  • valueSum: A mérések összege. A középérték lekéréséhez ossza el a következővel valueCount: .
  • valueCount: A hívásban trackMetric(..) összesített mérések száma.

Megjegyzés

A valueCount minimális értéke egy; maga a rekord egy bejegyzést jelöl.

Lapmegtekintések

Az eszköz- vagy weblapalkalmazásokban a rendszer alapértelmezés szerint elküldi az oldalnézet-telemetriát az egyes képernyők vagy lapok betöltésekor. Az alapértelmezett beállítást azonban módosíthatja úgy, hogy több vagy több időpontban is nyomon kövesse az oldalmegtekintéseket. Egy lapokat vagy paneleket megjelenítő alkalmazásban például érdemes lehet nyomon követni egy lapot, amikor a felhasználó új panelt nyit meg.

A rendszer tulajdonságokként és oldalmegtekintésként küldi el a felhasználói és munkamenet-adatokat, így a felhasználói és munkamenet-diagramok életre kelnek, amikor oldalnézeti telemetriai adatok vannak.

Egyéni lapmegtekintések

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 belül, megadhatja az URL-címet is:

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

Időzítési lapmegtekintések

Alapértelmezés szerint az oldalnézet betöltési idejeként jelentett idő attól a időponttól számítható, amikor a böngésző a kérést a böngésző oldalbetöltési eseményének meghívásáig küldi.

Ehelyett a következőket teheti:

  • Adjon meg 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 stopTrackPagea parancsotstartTrackPage.

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 társítja a start és stop hívásokat. Alapértelmezés szerint az aktuális lapnév.

A Metrikaböngészőben megjelenő lapbetöltési időtartamok az indítási és leállítási hívások közötti időközből származnak. Rajtad múlik, hogy mennyi idő alatt.

Laptelemetria a Log Analyticsben

A Log Analyticsben két tábla jeleníti meg a böngészőműveletek adatait:

  • pageViews: Adatokat tartalmaz az URL-címről és a lap címéről.
  • browserTimings: Adatokat tartalmaz az ügyfél teljesítményéről, például a bejövő adatok feldolgozásához szükséges időről.

Annak kiderítése, hogy a böngésző mennyi ideig tart a különböző oldalak feldolgozásához:

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

A különböző böngészők népszerűségének felfedezése:

pageViews
| summarize count() by client_Browser

Ha oldalmegtekintéseket szeretne társítani az AJAX-hívásokhoz, csatlakozzon a függőségekhez:

pageViews
| join (dependencies) on operation_Id

TrackRequest

A kiszolgáló SDK a HTTP-kérések naplózására szolgál TrackRequest .

Saját maga is meghívhatja, ha olyan környezetben szeretné szimulálni a kéréseket, amelyben nem fut a webszolgáltatás-modul.

A kéréstelemetria küldésének ajánlott módja, ha a kérés műveleti környezetként működik.

Műveleti környezet

A telemetriai elemeket a műveleti környezethez társítva korrelálhatja. A standard kéréskövetési modul ezt teszi a HTTP-kérés feldolgozása során küldött kivételek és egyéb események esetében. A Keresés és elemzés területen egyszerűen megtalálhatja a kérelemhez társított eseményeket a műveletazonosítójának használatával.

A korrelációval kapcsolatos további információkért lásd: Telemetriai korreláció az Application Insightsban.

Ha manuálisan követi nyomon a telemetriát, a telemetria korrelációjának legegyszerűbb módja az alábbi minta használata:

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űveleti környezet StartOperation beállításával együtt létrehoz egy megadott típusú telemetriai elemet. A telemetriai elemet küldi el, amikor a műveletet elveti, vagy ha explicit módon hívja meg a elemet StopOperation. Ha telemetriatípusként használja RequestTelemetry , az időtartam az indítás és a leállítás közötti időintervallumra van állítva.

A művelet hatókörén belül jelentett telemetriai elemek egy ilyen művelet gyermekévé válnak. A műveleti környezetek beágyazhatók.

A Keresés területen a műveletkörnyezetet használja a kapcsolódó elemek listájának létrehozásához.

Képernyőkép a Kapcsolódó elemek listáról.

További információ az egyéni műveletek nyomon követéséről: Egyéni műveletek nyomon követése az Application Insights .NET SDK-val.

Kérelmek a Log Analyticsben

Az Application Insights Analyticsben a kérések megjelennek a requests táblázatban.

Ha a mintavételezés működik, a itemCount tulajdonság értéke nagyobb, mint 1. Ez azt jelenti például, itemCount==10 hogy a 10 hívás trackRequest()közül a mintavételezési folyamat csak az egyiket továbbította. A kérések helyes számának és a kérésnevek szerint szegmentált átlagos időtartamnak a lekéréséhez használja a következő kódot:

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

TrackException

Kivételek küldése az Application Insightsnak:

A jelentések tartalmazzák a verem nyomkövetéseit.

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 észlelnek, így nem kell mindig explicit módon hívnia TrackException :

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

Kivételek a Log Analyticsben

Az Application Insights Analyticsben a kivételek megjelennek a exceptions táblázatban.

Ha a mintavételezés működik, a itemCount tulajdonság értéke nagyobb, mint 1. Ez azt jelenti például, itemCount==10 hogy a 10 hívás trackException()közül a mintavételezési folyamat csak az egyiket továbbította. A kivételtípusok szerint szegmentált kivételek helyes számának lekéréséhez használja a következő kódot:

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 szerkezetet széthúzva details továbbiakhoz juthat. Mivel ez a struktúra dinamikus, az eredményt a várt típusnak kell megadnia. Például:

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

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

exceptions
| join (requests) on operation_Id

TrackTrace

A használatával TrackTrace diagnosztizálhatja a problémákat, ha egy "útkövetési útvonalat" küld az Application Insightsnak. A diagnosztikai adatok egy részét elküldheti és megvizsgálhatja a Diagnosztikai keresésben.

A . NET-naplóadapterekben ezzel az API-val küldhet külső naplókat a portálra.

A Javában az Application Insights Java-ügynök automatikusan átküldi és elküldi a naplókat a portálnak.

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éloldali/böngészőoldali JavaScript

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

Naplózhat egy diagnosztikai eseményt, például beírhat vagy elhagyhat egy metódust.

Paraméter Leírás
message Diagnosztikai adatok. Sokkal hosszabb lehet, mint egy név.
properties A sztring és a sztring leképezése. A portál kivételeinek szűrésére további adatok szolgálnak. Alapértelmezés szerint ü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át message sokkal magasabb, mint a tulajdonságokra vonatkozó korlát. Ennek az TrackTrace az előnye, hogy viszonylag hosszú adatokat helyezhet el az üzenetben. Itt kódolhatja például a POST-adatokat.

Súlyossági szintet is hozzáadhat az üzenethez. A többi telemetriához hasonlóan tulajdonságértékeket is hozzáadhat a különböző nyomkövetési csoportok szűréséhez vagy kereséséhez. 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és területen ezután egyszerűen kiszűrheti egy adott súlyossági szint összes üzenetét, amely egy adott adatbázishoz kapcsolódik.

Nyomkövetések a Log Analyticsben

Az Application Insights Analyticsben a táblában traces megjelenő hívásokTrackTrace.

Ha a mintavételezés működik, a itemCount tulajdonság értéke nagyobb, mint 1. Ez azt jelenti például, itemCount==10 hogy a 10 hívás trackTrace()közül a mintavételezési folyamat csak az egyiket továbbította. A nyomkövetési hívások megfelelő számának lekéréséhez használja a következőhöz hasonló kódot: traces | summarize sum(itemCount).

TrackDependency

TrackDependency A hívással nyomon követheti a külső kódhoz intézett hívások válaszidejének és sikerességének arányát. Az eredmények megjelennek a függőségi diagramokon a portálon. A következő kódrészletet minden függőségi híváshoz hozzá kell adni.

Megjegyzés

A .NET és a .NET Core esetében használhatja a TelemetryClient.StartOperation (bővítmény) metódust is, amely kitölti a DependencyTelemetry korrelációhoz szükséges tulajdonságokat és más tulajdonságokat, például a kezdési időpontot és az időtartamot, így nem kell egyéni időzítőt létrehoznia az alábbi példákhoz hasonlóan. További információt az Egyéni műveletek nyomon követése az Application Insights .NET SDK-val című cikk kimenő függőségek nyomon követéséről szóló szakaszában talál.

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óIDK-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 működéséhez telepítenie kell egy ügynököt a kiszolgálón.

A Javában számos függőségi hívás automatikusan nyomon követhető az Application Insights Java-ügynökkel.

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

Ha ki szeretné kapcsolni a standard függőségkövetési modult a C#-ban, szerkessze ApplicationInsights.config , és törölje a hivatkozását a következőre DependencyCollector.DependencyTrackingTelemetryModule: . Javával kapcsolatban lásd: Adott automatikusan kiszúrt telemetriai adatok mellőzése.

Függőségek a Log Analyticsben

Az Application Insights Analyticsben a trackDependency hívások megjelennek a dependencies táblázatban.

Ha a mintavételezés működik, a itemCount tulajdonság 1-nél nagyobb értéket jelenít meg. Ez azt jelenti például, itemCount==10 hogy a 10 hívás trackDependency()közül a mintavételezési folyamat csak az egyiket továbbította. A célösszetevő szerint szegmentált függőségek megfelelő számának lekéréséhez használja a következő kódokat:

dependencies
| summarize sum(itemCount) by target

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

dependencies
| join (requests) on operation_Id

Adatok kiürítése

Az SDK általában rögzített időközönként, általában 30 másodperccel, vagy ha a puffer megtelt, általában 500 elemet küld. Bizonyos esetekben érdemes lehet kiüríteni a puffert. Ilyen például, ha az SDK-t egy leállított alkalmazásban használja.

.NET

A használata Flush()esetén a következő mintát javasoljuk:

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

A használata FlushAsync()esetén a következő mintát javasoljuk:

await telemetryClient.FlushAsync()
// No need to sleep

Javasoljuk, hogy az alkalmazás leállítása során mindig ürítsen, hogy a telemetriai adatok ne vesszenek el.

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.

Megjegyzés

A Java és JavaScript SDK-k automatikusan kiürítik az alkalmazás leállítását.

Hitelesített felhasználók

A webalkalmazásokban a felhasználókat alapértelmezés szerint cookie-k azonosítják . Előfordulhat, hogy egy felhasználó többször is beleszámít, ha egy másik gépről vagy böngészőből éri el az alkalmazást, vagy törli a cookie-kat.

Ha a felhasználók bejelentkeznek az alkalmazásba, pontosabb számot kaphat, ha beállítja a hitelesített felhasználói azonosítót a böngésző kódjában:

JavaScript

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

Egy ASP.NET webes 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 olyan azonosítónak kell lennie, amely egyedi az adott felhasználó számára. Nem tartalmazhat szóközöket vagy karaktereket ,;=|.

A felhasználói azonosító is be van állítva egy munkamenet-cookie-ban, és elküldi 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űrheti és kereshet rajta.

Ha az alkalmazás fiókokba csoportosítja a felhasználókat, a fiók azonosítóját is átadhatja. Ugyanezek a karakterkorlátozások érvényesek.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

A Metrikaböngészőben létrehozhat egy diagramot, amely a Felhasználók, a Hitelesített és a Felhasználói fiókokat számlálja meg.

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

Megjegyzés

A .NET Core SDK ApplicationInsightsServiceOptions osztályában található EnableAuthenticationTrackingJavaScript tulajdonság leegyszerűsíti az Application Insights JavaScript SDK által küldött nyomkövetések hitelesítési azonosítójaként a felhasználónév beszúrásához szükséges JavaScript-konfigurációt.

Ha ez a tulajdonság értékre truevan állítva, a rendszer az ASP.NET Core felhasználójának felhasználónevét nyomtatja ki az ügyféloldali telemetriával együtt. Emiatt a manuális hozzáadásra appInsights.setAuthenticatedUserContext már nincs szükség, mert az SDK már beszúrta ASP.NET Core. Az Auth-azonosítót a rendszer arra a kiszolgálóra is elküldi, ahol a .NET Core SDK-ja azonosítja és bármely kiszolgálóoldali telemetriához használja a JavaScript API-referencia alapján.

Az olyan JavaScript-alkalmazások esetében, amelyek nem ugyanúgy működnek, mint ASP.NET Core MVC, például SPA-webalkalmazások, manuálisan kell hozzáadniaappInsights.setAuthenticatedUserContext.

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, metrikákhoz, oldalmegtekintésekhez, kivételekhez és egyéb telemetriai adatokhoz.

A tulajdonságok olyan sztringértékek, amelyekkel szűrheti a telemetria adatait a használati jelentésekben. Ha például az alkalmazás több játékot is kínál, minden eseményhez csatolhatja a játék nevét, így láthatja, hogy mely játékok népszerűbbek.

A sztring hosszának korlátja 8192. Ha nagy adattömböket szeretne küldeni, használja a következő üzenetparamétert TrackTrace: .

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

A metrikaértékek helyes megjelenítéséhez a metrikaértéknek 0-nál nagyobbnak vagy egyenlőnek kell lennie.

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

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

Győződjön meg arról, hogy nem naplózza a személyazonosításra alkalmas adatokat a tulajdonságokban.

Alternatív módszer a tulajdonságok és metrikák beállítására

Ha kényelmesebb, egy esemény paramétereit 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 telemetriai elempéldányt (event ebben a példában) többszöri híváshoz Track*() . Ez a gyakorlat azt okozhatja, hogy helytelen konfigurációval küldi el a telemetriát.

Egyéni mérések és tulajdonságok a Log Analyticsben

A Log Analyticsben az egyéni metrikák és tulajdonságok az customMeasurements egyes telemetriarekordok és customDimensions -attribútumok között jelennek meg.

Ha például egy "játék" nevű tulajdonságot ad hozzá a kérelem telemetriai adataihoz, ez a lekérdezés megszámolja a "játék" különböző értékeinek előfordulását, és megjeleníti az egyéni metrika "pontszámának" átlagát:

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

Figyelje meg az alábbiakat:

  • Amikor kinyer egy értéket a vagy customMeasurements a customDimensions JSON-ból, az dinamikus típussal rendelkezik, ezért el kell végeznie a vagy todoublea tostring értéket.
  • A mintavételezés lehetőségének figyelembe vételéhez használja sum(itemCount) a következőt: count().

Időzítési események

Előfordulhat, hogy egy művelet végrehajtásához diagramot szeretne készíteni. Előfordulhat például, hogy tudni szeretné, hogy a felhasználók mennyi ideig tartanak, amíg a játékban választanak. Az információk beszerzéséhez használja a mérési 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 telemetriai adatok alapértelmezett tulajdonságai

Ha az ön által írt egyéni események alapértelmezett tulajdonságértékeit szeretné beállítani, állítsa be őket egy TelemetryClient példányban. Ezek az ügyféltől küldött összes telemetriai elemhez vannak csatolva.

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árak alapértelmezett értékeit.

JavaScript-webügyfelek esetén javaScript-telemetriai inicializálókat használjon.

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

Telemetria mintája, szűrése és feldolgozása

Írhat kódot a telemetriai adatok feldolgozásához, mielőtt elküldené azt az SDK-ból. A feldolgozás magában foglalja a szabványos telemetriai modulokból, például a HTTP-kérések gyűjtéséből és a függőséggyűjtésből küldött adatokat.

Tulajdonságok hozzáadása a telemetriához a implementálással ITelemetryInitializer. Hozzáadhat például más tulajdonságokból számított verziószámokat vagy értékeket.

A szűrés módosíthatja vagy elvetheti a telemetriát, mielőtt elküldené az SDK-ból a implementálással ITelemetryProcessor. Ön szabályozza, hogy mi legyen elküldve vagy elvetve, de figyelembe kell vennie a metrikákra gyakorolt hatást. Az elemek elvetésének módjától függően 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 anélkül teszi meg, hogy hatással lenne a megjelenített metrikákra. Mindezt anélkül, hogy befolyásolná a problémák diagnosztizálását a kapcsolódó elemek, például a kivételek, a kérések és az oldalmegtekintések közötti navigálással.

További információ: A telemetria szűrése és előfeldolgozása az Application Insights SDK-ban.

Telemetria letiltása

A telemetriai adatok gyűjtésének és átvitelének dinamikus leállítása és elindítása :

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 fűzzön megjegyzést a ApplicationInsights.configvonatkozó soraihoz. Ilyen például, 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 inicializáláskor történő letiltásához az SDK inicializálási kódjához lánckonfigurációs módszereket kell létrehozni.

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

Ha le szeretné tiltani ezeket a gyűjtőket az inicializálás után, használja a Következő konfigurációs objektumot: applicationInsights.Configuration.setAutoCollectRequests(false).

Fejlesztői mód

A hibakeresés során célszerű a telemetria gyorsítását a folyamaton keresztül, hogy azonnal láthassa az eredményeket. Más üzeneteket is kap, amelyek segítenek a telemetriával kapcsolatos problémák nyomon követésében. Kapcsolja ki éles környezetben, mert lelassíthatja az alkalmazást.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

A Node.js esetében engedélyezheti a fejlesztői módot, ha engedélyezi a belső naplózást a -en keresztülsetInternalLogging, és a értékre 0állítja maxBatchSize a beállítást, ami miatt a telemetriát a rendszer az adatgyűjtés után azonnal elküldi.

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

A kiválasztott egyéni telemetria rendszerállapotkulcsának beállítása

C#

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

Dinamikus kialakítási kulcs

A fejlesztési, tesztelési és éles környezetekből származó telemetriai adatok keveredésének elkerülése érdekében a környezettől függően létrehozhat különálló Application Insights-erőforrásokat , és módosíthatja a kulcsaikat.

Ahelyett, hogy lekérte volna a rendszerállapotkulcsot 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 global.aspx.cs 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 weblapokon érdemes lehet a webkiszolgáló állapotából beállítani ahelyett, hogy szó szerint a szkriptbe kódolnia. Például egy ASP.NET alkalmazásban létrehozott weblapon:

JavaScript a Razorban

<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

TelemetryClient Egy Context tulajdonsággal rendelkezik, amely az összes telemetriai adattal együtt elküldött értékeket 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 ezeket az értékeket saját maga állítja be, vegye fontolóra a megfelelő sor eltávolítását a ApplicationInsights.config , hogy az értékek és a standard értékek ne keveredhessenek össze.

  • Összetevő: Az alkalmazás és annak verziója.
  • Eszköz: Annak az eszköznek az adatai, amelyen az alkalmazás fut. A webalkalmazásokban az a kiszolgáló vagy ügyféleszköz, amelyről a telemetriát küldi a rendszer.
  • InstrumentationKey: Az Azure Application Insights-erőforrása, ahol a telemetria megjelenik. Általában a -től ApplicationInsights.configveszik fel.
  • Hely: Az eszköz földrajzi helye.
  • Művelet: A webalkalmazásokban az aktuális HTTP-kérés. Más alkalmazástípusokban ezt az értéket úgy állíthatja be, hogy csoportosítsa az eseményeket.
    • Azonosító: Olyan létrehozott érték, amely különböző eseményeket korrelál, így amikor a Diagnosztikai keresésben megvizsgál egy eseményt, megkeresheti a kapcsolódó elemeket.
    • Név: Egy azonosító, amely általában a HTTP-kérelem URL-címe.
    • Szintetikusforrás: Ha nem null értékű vagy üres, 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 Metrics Explorer számításaiból.
  • Munkamenet: A felhasználó munkamenete. Az azonosító egy generált értékre van állítva, amely akkor változik, ha a felhasználó egy ideje nem aktív.
  • Felhasználó: Felhasználói adatok.

Korlátok

Az alkalmazásonkénti metrikák és események, azaz a rendszerállapot-kulcsok száma korlátozott. A korlátozások a választott díjszabási csomagtól függően változnak.

Erőforrás Alapértelmezett korlát Felső korlát Jegyzetek
Napi teljes adatmennyiség 100 GB Lépjen kapcsolatba az ügyfélszolgálattal. Egy korlát beállításával csökkenthető az adatmennyiség. Ha több adatra van szüksége, a portálon akár 1000 GB-ra is növelheti a korlátot. Az 1000 GB-nál nagyobb kapacitások esetén küldjön e-mailt a címre AIDataCap@microsoft.com.
Throttling 32 000 esemény/másodperc Lépjen kapcsolatba az ügyfélszolgálattal. 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 730 nap Ez az erőforrás a naplókhoz tartozik.
Adatmegőrzési metrikák 90 nap 90 nap Ez az erőforrás a Metrics Explorerhez tartozik.
Rendelkezésre állási többlépéses teszt részletes eredménymegőrzése 90 nap 90 nap Ez az erőforrás minden lépésről részletes eredményeket biztosít.
Telemetriaelem maximális mérete 64 KB 64 KB
Telemetriaelemek maximális száma kötegenként 64,000 64,000
Tulajdonság- és metrikanév hossza 150 150 Lásd : Típusséma.
Tulajdonságérték-sztring hossza 8,192 8,192 Lásd : Típusséma.
Nyomkövetési és kivételüzenet hossza 32,768 32,768 Lásd : Típusséma.
Rendelkezésre állási tesztek száma alkalmazásonként 100 100
Profiler és pillanatkép adatmegőrzése Két hét Vegye fel a kapcsolatot az ügyfélszolgálattal. A maximális megőrzési korlát hat hónap.
Profiler naponta küldött adatai Nincs korlát Nincs korlát
Naponta küldött pillanatkép-adatok Naponta 30 pillanatkép monitorozott alkalmazásonként Nincs korlát Az alkalmazásonként gyűjtött pillanatképek száma konfigurációval módosítható.

A díjszabással és kvótával kapcsolatos további információkért lásd: Application Insights-számlázás.

Az adatsebesség-korlát elérésének elkerülése érdekében használjon mintavételezést.

Az adatok megőrzésének időtartamáról az Adatmegőrzés és adatvédelem című témakörben olvashat.

Referenciadokumentumok

SDK-kód

Gyakori kérdések

Miért hiányoznak a telemetriai adatok?

Mindkét TelemetriaCsatorna elveszíti a pufferelt telemetriát, ha nem üríti ki egy alkalmazás leállítása előtt.

Az adatvesztés elkerülése érdekében ürítse ki a TelemetryClientet, amikor egy alkalmazás leáll.

További információ: Adatok kiürítése.

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

Nincsenek. Ezeket nem kell becsomagolnia a try-catch záradékba. Ha az SDK problémákat tapasztal, naplózza az üzeneteket a hibakeresési konzol kimenetében, és ha az üzenetek átjutnak a Diagnosztikai keresésben.

Van REST API, amely adatokat szeretne lekérni a portálról?

Igen, az adatelérési API. Az adatok kinyerésének egyéb módjai közé tartozik a Power BI is, ha munkaterület-alapú erőforrásra migrált vagy folyamatos exportálást végzett, ha még mindig klasszikus erőforráson dolgozik.

Miért nem veszik figyelembe az egyéni eseményekre és metrikákra vonatkozó API-k hívásait?

Az Application Insights SDK nem kompatibilis az automatikus kialakítással. Ha az automatikus kialakítás engedélyezve van, a rendszer figyelmen kívül hagyja a hívások és Track() más egyéni események és metrikák API-jait.

Kapcsolja ki az automatikus kialakítást a Azure Portal a App Service lap Application Insights lapján, vagy állítsa a következőreApplicationInsightsAgent_EXTENSION_VERSION: disabled.

Következő lépések