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

  • Cikk

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, webes ügyfelekről és webkiszolgálókról. Az Alkalmazás Elemzések alapszintű telemetriai API használatával egyéni eseményeket és metrikákat küldhet, valamint a standard telemetria saját verzióit. Ez az API ugyanaz az API, amelyet a standard alkalmazás Elemzések adatgyűjtők használnak.

Feljegyzés

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

API összefoglaló

Az alapvető API minden platformon egységes, néhány változattól eltekintve, 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 figyelésére 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, mint például az üzenetsorok hossza, amelyek nem kapcsolódnak adott eseményekhez.
TrackException Naplózási kivételek a diagnózishoz. Nyomon követheti, hogy hol fordulnak elő más eseményekhez képest, és vizsgálja meg a verem nyomkövetését.
TrackRequest A kiszolgálói teljesítményelemzési kérelmek gyakoriságának és időtartamának naplózása.
TrackTrace Erőforrás-diagnosztikai naplóüzenetek. Külső naplókat is rögzíthet.
TrackDependency Az alkalmazás által használt 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 tulajdonságokat és metrikákat csatolhat.

Előkészületek

Ha még nem rendelkezik hivatkozással az Application Elemzések SDK-val kapcsolatban:

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

  • Az eszköz vagy a webkiszolgáló kódja tartalmazza a következőket:

    C#:using Microsoft.ApplicationInsights;

    Visual Basic:Imports Microsoft.ApplicationInsights

    Java:import com.microsoft.applicationinsights.TelemetryClient;

    Node.jsvar applicationInsights = require("applicationinsights");:

TelemetryClient-példány lekérése

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

Az ASP.NET Core-alkalmazások és a .NET/.NET Core-alkalmazások nem HTTP/Feldolgozója esetén a függőséginjektálási TelemetryClient tárolóból szerezze be a példányt a vonatkozó dokumentációjukban leírtak szerint.

Ha az Azure Functions v2+ vagy az Azure WebJobs v3+-ot használja, tekintse meg az Azure Functions monitorozását.

C#

private TelemetryClient telemetry = new TelemetryClient();

Ha egy üzenet jelzi, hogy ez a módszer elavult, további információt a microsoft/Application Elemzések-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 több példányt 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. Beállíthat olyan tulajdonságokat, mint például UserIdDeviceId a gép azonosítása. 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("...");

Node.js projektekben new applicationInsights.TelemetryClient(instrumentationKey?) létrehozhat egy új példányt. Ezt a megközelítést csak olyan forgatókönyvek esetén javasoljuk, amelyek elszigetelt konfigurációt igényelnek a singletontól defaultClient.

TrackEvent

Az Alkalmazás Elemzések az egyéni események olyan adatpontok, amelyeket 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. Előfordulhat például, hogy nyomon szeretné 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ó 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 a Log Analyticsben

A telemetria az customEvents Alkalmazás Elemzések Naplók lapon vagy a használati felületen található táblázatban érhető el. Előfordulhat, hogy az események a Click Analytics automatikus gyűjtemény beépülő modulból trackEvent(..)származnak.

Ha a mintavételezés folyamatban van, a itemCount tulajdonság értéke nagyobb, mint 1. Ez azt jelenti például, itemCount==10 hogy 10 hívásból trackEvent()csak egyet továbbított a mintavételezési folyamat. Az egyéni események helyes számának lekéréséhez használja a customEvents | summarize sum(itemCount)következő kódot: .

Feljegyzés

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

GetMetric

Ha tudni szeretné, hogyan használhatja a hívást a GetMetric() helyileg előre összesített metrikák rögzítésére .NET- és .NET Core-alkalmazásokhoz, tekintse meg az egyéni metrikák gyűjteményét a .NET-ben és a .NET Core-ban.

TrackMetric

Feljegyzés

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üldené őket. Használja az egyik túlterhelést egy GetMetric(..) 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 egy használati esete az eseménytelemetria esetében. Lásd: TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Az alkalmazás Elemzések olyan metrikákat ábrázolhat, amelyek nincsenek adott eseményekhez csatolva. Monitorozhat például egy üzenetsor hosszát rendszeres időközönként. A metrikáknál az egyes mérések kevésbé érdekesek, mint a variációk és trendek, ezért a statisztikai diagramok hasznosak.

Ha metrikákat szeretne küldeni az Alkalmazás Elemzések, 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 Alkalmazás Elemzések.

    Tegyük fel például, hogy rendelkezik egy olyan metrikával, amely egy tároló elemeinek 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 is felhívna TrackMetric . Először adja át az értéket 3 , majd adja át az értéket -2. Az alkalmazás Elemzések mindkét értéket tárolja.

  • Összesítés. Ha metrikákkal dolgozik, minden egyes 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.

    Az előző példában az adott időszak összesített metrikaösszege és 1 a metrikaértékek száma.2 Az összesítési módszer használata esetén időszakonként csak egyszer hív meg TrackMetric , és elküldi az összesített értékeket. Ezt a megközelítést azért javasoljuk, mert jelentősen csökkentheti a költségeket és a teljesítményterhelést azáltal, hogy kevesebb adatpontot küld az Alkalmazás Elemzések, miközben továbbra is összegyűjti az összes releváns információt.

Példák egyetlen értékre

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 customMetrics Application Elemzések Analytics táblájában érhető el. Minden sor egy hívást trackMetric(..) jelöl 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.

Feljegyzés

a valueCount értéke legalább egy; maga a rekord egy bejegyzést jelöl.

Oldalmegtekintések

Egy eszköz- vagy weblapalkalmazásban a rendszer alapértelmezés szerint elküldi a lapnézet telemetriájá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 oldalnézetekként küldi el a felhasználói és munkamenet-adatokat, így a felhasználói és a munkamenet-diagramok életre kelnek, amikor oldalnézeti telemetria van.

Egyéni oldalmegtekintések

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

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

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

Oldalmegtekintések időzítése

Alapértelmezés szerint a lapnézet betöltési idejeként jelentett idő attól számítható ki, hogy a böngésző mikor küldi el a kérést a böngésző lapbetöltési eseményének meghívásáig.

Ehelyett a következőkre van lehetőség:

  • Adjon meg 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 startTrackPage és stopTrackPagea .

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 hívások indítását és leállítását. 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 intervallumból származnak. Rajtad múlik, hogy valójában milyen időközönként.

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: Olyan adatokat tartalmaz az ügyfél teljesítményéről, mint a bejövő adatok feldolgozásához szükséges idő.

Annak megkeresé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óIDK HTTP-kérések naplózására szolgál TrackRequest .

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

A kérelemtelemetria 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 összekapcsolhatja a műveleti környezettel való társítással. A szabványos 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ó használatával.

A korrelációról további információt az Application Elemzések telemetriai korrelációjában talál.

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 akkor küldi el, amikor ön a művelettől megszabadul, vagy ha explicit módon hívja meg StopOperationa műveletet. Ha telemetriatípusként használja RequestTelemetry , annak időtartama a kezdés és a leállítás közötti időintervallumra van állítva.

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

A Keresésben 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.

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 az Application Elemzések .NET SDK-val.

Kérelmek a Log Analyticsben

Az Application Elemzések Analyticsben a kérelmek megjelennek a requests táblázatban.

Ha a mintavételezés folyamatban van, a itemCount tulajdonság értéke nagyobb, mint 1. Ez azt jelenti például, itemCount==10 hogy 10 hívásból trackRequest()csak egyet továbbított a mintavételezési folyamat. A kérések helyes számának és a kérelmek neve szerint szegmentált átlagos időtartamának 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 Alkalmazás Elemzések:

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

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

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

Kivételek a Log Analyticsben

Az Application Elemzések Analyticsben kivételek jelennek meg a exceptions táblában.

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

exceptions
| summarize sum(itemCount) by type

A legfontosabb veremadatok többsége már külön változókba van kinyerve, de a struktúrát szétszedheti, details hogy többet kapjon. Mivel ez a struktúra dinamikus, az eredményt a várt típusra kell leadnia. Példa:

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

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

exceptions
| join (requests) on operation_Id

TrackTrace

A TrackTrace problémák diagnosztizálásához használhatja a "breadcrumb trail" alkalmazásba való küldésével Elemzések. A diagnosztikai adatok darabjait elküldheti, és megvizsgálhatja őket a Diagnosztikai keresésben.

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

A Java-ban az alkalmazás automatikusan Elemzések a Java-ügynököt, és naplókat küld 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é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 térképe. További adatokkal szűrheti a kivételeket a portálon. 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 az előnye TrackTrace , hogy viszonylag hosszú adatokat helyezhet el az üzenetben. Itt például a POST-adatokat kódolhatja.

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élda:

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ésben 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 Elemzések Analyticsben a táblában traces megjelenő hívásokTrackTrace.

Ha a mintavételezés folyamatban van, a itemCount tulajdonság értéke nagyobb, mint 1. Ez azt jelenti például, itemCount==10 hogy 10 hívásból trackTrace()csak egyet továbbított a mintavételezési folyamat. A nyomkövetési hívások helyes számának lekéréséhez használjon olyan kódot, mint a traces | summarize sum(itemCount).

TrackDependency

A hívással TrackDependency nyomon követheti a külső kódhoz intézett hívások válaszidejének és sikerességi arányának mértékét. Az eredmények a portál függőségi diagramjaiban jelennek meg. A következő kódrészletet mindenhol hozzá kell adni, ahol függőségi hívást kezdeményeznek.

Feljegyzés

A .NET és a .NET Core esetében alternatív megoldásként használhatja a TelemetryClient.StartOperation (bővítmény) metódust, amely kitölti a DependencyTelemetry korrelációhoz szükséges tulajdonságokat és néhány egyéb tulajdonságot, 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ókért tekintse meg a kimenő függőségek nyomon követéséről szóló szakaszt az egyéni műveletek nyomon követése az Application Elemzések .NET SDK-val című témakörben.

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ó SDK-jai 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 az adatbázisokat és a REST API-kat. A modul működéséhez telepítenie kell egy ügynököt a kiszolgálóra.

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

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

Ha ki szeretné kapcsolni a standard függőségkövetési modult a C#-ban, szerkessze az Application Elemzések.config fájlt, és törölje a hivatkozásátDependencyCollector.DependencyTrackingTelemetryModule. A Java esetében lásd : Adott automatikus telemetriai adatok letiltása.

Függőségek a Log Analyticsben

Az Application Elemzések AnalyticsbentrackDependency a hívások megjelennek a dependencies táblázatban.

Ha a mintavételezés működik, a itemCount tulajdonság értéke 1-nél nagyobb. Ez azt jelenti például, itemCount==10 hogy 10 hívásból trackDependency()csak egyet továbbított a mintavételezési folyamat. A célösszetevő szerint szegmentált függőségek helyes 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éseikkel, használjon egy 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 a puffer megtelt állapotában küld adatokat, ami általában 500 elem. 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álat Flush()során a következő mintát javasoljuk:

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

A használat FlushAsync()során a következő mintát javasoljuk:

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

Javasoljuk, hogy az alkalmazásleállítás részeként 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.

Feljegyzés

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

Hitelesített felhasználók

Egy webalkalmazásban a felhasználókat alapértelmezés szerint cookie-k azonosítják. Előfordulhat, hogy egy felhasználót többször is meg kell számolni, 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, pontosabb számot kaphat 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 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 az adott felhasználóra jellemző azonosító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 elküldi a kiszolgálónak. Ha a kiszolgáló 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ókba 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 Metrics Explorerben létrehozhat egy diagramot, amely megszámlálja a felhasználókat, a hitelesített és a felhasználói fiókokat.

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

Feljegyzés

A .NET Core SDK Application Elemzések ServiceOptions osztályában található EnableAuthenticationTrackingJavaScript tulajdonság leegyszerűsíti az alkalmazás által Elemzések JavaScript SDK által küldött nyomkövetések hitelesítési azonosítójaként a felhasználónevet injektáló JavaScript-konfigurációt.

Ha ez a tulajdonság be van állítvatrue, a rendszer az ASP.NET Core-ban lévő felhasználó felhasználónevet 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 azt már beszúrta az SDK a ASP.NET Core-hoz. A hitelesítési azonosítót a rendszer arra a kiszolgálóra is elküldi, ahol a .NET Core SDK-ja azonosítja, és a JavaScript API-referencia alapján minden kiszolgálóoldali telemetriához használja.

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áadnia appInsights.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, oldalnézetekhez, kivételekhez és egyéb telemetriai adatokhoz.

A tulajdonságok olyan sztringértékek, amelyekkel szűrheti a telemetriát 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 sztringhossz 8192 lehet. 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. Érdemes lehet például megnézni, hogy a játékosok által elért pontszámok fokozatosan növekednek-e. A grafikonok szegmentáltak lehetnek az eseményhez küldött tulajdonságok alapján, így különálló vagy halmozott gráfokat kaphat a különböző játékokhoz.

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

Feljegyzés

Győződjön meg arról, hogy nem naplózza a személyazonosításra alkalmas adatokat 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 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 a telemetriai adatok helytelen konfigurációval lesznek elküldve.

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 telemetriai rekordokban és customDimensions attribútumokban jelennek meg.

Ha például hozzáad egy "game" nevű tulajdonságot 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:

Időzítési események

Néha érdemes diagramot készíteni, hogy mennyi ideig tart egy művelet végrehajtása. Érdemes lehet például tudnia, hogy a felhasználók mennyi ideig tartanak, amíg megfontolják a választásokat egy játékban. 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 meg szeretné adni az alapértelmezett tulajdonságértékeket az ön által írt egyéni események némelyikéhez, á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ülírhatják a tulajdonságszótárak alapértelmezett értékeit.

JavaScript-webügyfélszámítógépek esetén JavaScript-telemetria-inicializálókat használjon.

Ha tulajdonságokat szeretne hozzáadni az összes telemetriához, beleértve a standard gyűjteménymodulokból származó adatokat is, implementálja a elemet ITelemetryInitializer.

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

Lásd: Szűrés és előfeldolgozás telemetria az alkalmazás Elemzések SDK-ban.

Telemetriai adatok 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 az Alkalmazás Elemzések.config megfelelő 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 lánckonfigurációs módszereket kell az SDK inicializálási kódjához kapcsolni.

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 Konfiguráció objektumot: applicationInsights.Configuration.setAutoCollectRequests(false).

Fejlesztői mód

A hibakeresés során hasznos, ha a telemetriát a folyamaton keresztül gyorsítja, 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 a belső naplózás setInternalLogging engedélyezésével és beállításával maxBatchSize0engedélyezheti a fejlesztői módot, 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 rendszerállapot-kulcs

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

Ahelyett, hogy lekérte volna a rendszerállapotkulcsot a konfigurációs fájlból, beállíthatja a kódban. Állítsa be a kulcsot 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;

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 Környezeti 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élda:

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

Ha ezeket az értékeket saját maga állítja be, távolítsa el a megfelelő sort az Application Elemzések.config alkalmazásból, hogy az értékek és a standard értékek ne keveredhessenek össze.

  • Összetevő: Az alkalmazás és annak verziója.
  • Eszköz: Adatok arról az eszközről, amelyen az alkalmazás fut. A webalkalmazásokban az a kiszolgáló vagy ügyféleszköz, amelyről a telemetriát elküldi a rendszer.
  • InstrumentationKey: Az alkalmazás Elemzések erőforrást az Azure-ban, ahol megjelenik a telemetria. Általában onnan veszik fel ApplicationInsights.config.
  • Hely: Az eszköz földrajzi helye.
  • Művelet: 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 generált érték, amely különböző eseményeket korrelál, így amikor bármilyen eseményt megvizsgál a Diagnosztikai keresésben, megkeresheti a kapcsolódó elemeket.
    • Név: Egy azonosító, általában a HTTP-kérés 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, vagyis 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 Maximális korlát Jegyzetek
Napi teljes adatmennyiség 100 GB Kapcsolatfelvétel az ügyfélszolgálattal. Az adatok csökkentéséhez beállíthat egy korlátot. 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 következő címre AIDataCap@microsoft.com: .
Szabályozás 32 000 esemény/másodperc Kapcsolatfelvétel 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 naplókhoz készült.
Adatmegőrzési metrikák 90 nap 90 nap Ez az erőforrás a Metrics Explorerhez készült.
Rendelkezésre állási többlépéses teszt részletes eredményeinek megőrzése 90 nap 90 nap Ez az erőforrás minden lépésről részletes eredményeket biztosít.
Telemetriai elemek 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 a típussémákat.
Tulajdonságérték-sztring hossza 8,192 8,192 Lásd a típussémákat.
Nyomkövetési és kivételüzenet hossza 32,768 32,768 Lásd a típussémákat.
Rendelkezésre állási tesztek száma alkalmazásonként Elemzések erőforrásonként 100 100
Profiler és pillanatkép adatmegőrzése Két hét Kapcsolatfelvétel az ügyfélszolgálattal. A maximális megőrzési korlát hat hónap.
Profiler naponta küldött adatai Korlátlan Nincs korlát.
Naponta küldött pillanatkép-adatok Naponta 30 pillanatkép figyelt 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 tekintse meg az Alkalmazás Elemzések számlázást.

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 további információt az adatmegőrzés és az adatvédelem című témakörben talál.

Referenciadokumentumok

SDK-kód

Gyakori kérdések

Ez a szakasz választ ad a gyakori kérdésekre.

Miért hiányoznak a telemetriai adatok?

Mindkét telemetriacsatornák elveszítik a pufferelt telemetriát, ha az alkalmazás leállítása előtt nincs kiürítve.

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

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

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

Nincs. 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 ha továbbra is 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 alkalmazás Elemzések SDK nem kompatibilis az autoinstrumentációval. Ha az autoinstrumentáció engedélyezve van, a rendszer figyelmen kívül hagyja az egyéni eseményekre Track() és metrikákra vonatkozó API-kat.

Kapcsolja ki az autoinstrumentációt az Azure Portalon az App Service lap Alkalmazás Elemzések lapján, vagy állítsa be a következőre ApplicationInsightsAgent_EXTENSION_VERSIONdisabled: .

Miért egyenlőtlenek a keresési és metrikadiagramok számai?

A mintavételezés csökkenti az alkalmazásból a portálra küldött telemetriai elemek (például kérések és egyéni események) számát. A Keresés nézetben láthatja a fogadott elemek számát. Az események számát megjelenítő metrikadiagramokon az eredeti események száma látható.

Minden továbbított elem egy tulajdonságot itemCount hordoz, amely azt mutatja, hogy hány eredeti eseményt jelöl az elem. A mintavételezés működés közbeni megfigyeléséhez futtassa ezt a lekérdezést a Log Analyticsben:

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

Hogyan állíthatok be riasztást egy eseményen?

Az Azure-riasztások csak metrikákon vannak. Hozzon létre egy egyéni metrikát, amely túllép egy értékküszöböt, amikor az esemény bekövetkezik. Ezután állítson be egy riasztást a metrikára. Értesítést kap, ha a metrika mindkét irányban átlépi a küszöbértéket. Az első kereszteződésig nem kap értesítést, függetlenül attól, hogy a kezdeti érték magas vagy alacsony. Mindig van néhány perc késés.

Következő lépések