Megosztás a következőn keresztül:

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

Figyelemfelhívás

Javasoljuk az Azure Monitor OpenTelemetry Distro használatát az új alkalmazások vagy ügyfelek számára az Azure Monitor Application Insights használatához. Az Azure Monitor OpenTelemetry Distro az Application Insights SDK-hoz hasonló funkciókat és élményt nyújt. Az Application Insights SDK-ból a .NET, a Node.js és a Python áttelepítési útmutatóival migrálható, de még dolgozunk néhány további funkció hozzáadásán a visszamenőleges kompatibilitás érdekében.

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 Application Insights alapvető telemetriai API-jának használatával egyéni eseményeket és metrikákat küldhet, valamint a standard telemetriai adatok saját verzióit. Ez az API ugyanaz az API, amelyet a standard Application Insights-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 sztringekre 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 Kivételek naplózása a diagnózis céljából. Követni tudjuk, hogy hol történnek az események másokhoz képest, és megvizsgálni a veremnyomokat.
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. Harmadik féltől származó 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.

Mielőtt elkezdenéd

Ha még nem rendelkezik hivatkozással az Application Insights SDK-ra:

  • Adja hozzá az Application Insights 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

    Jáva:import com.microsoft.applicationinsights.TelemetryClient;

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

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

Szerezzen be egy példányt a TelemetryClient-ből (kivéve a JavaScriptet a weblapokon):

Az ASP.NET Core-alkalmazások és Nem HTTP/.NET/.NET Core feldolgozó alkalmazások esetén szerezzen egy példányt a függőséginjektálási TelemetryClient tárolóból 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/ApplicationInsights-dotnet#1152 című témakörben talál.

Visual Basic

Private Dim telemetry As New TelemetryClient

Jáva

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient szálbiztos.

ASP.NET- és Java-projektek esetén a rendszer automatikusan rögzíti a bejövő HTTP-kéréseket. Előfordulhat, hogy az alkalmazás más moduljaihoz szeretne több TelemetryClient példányt létrehozni. 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. Az információ minden eseményhez csatolva van, amelyet a példány küld.

C#

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

Jáva

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

Node.js projektekben új példányt hozhat létre new applicationInsights.TelemetryClient(instrumentationKey?) segítségével. 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 Application Insightsban az egyéni események olyan adatpontok, amelyeket a Metrics Explorerben összesített számként és a diagnosztikai keresésben egyéni 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 követnek el 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")

Jáva

telemetry.trackEvent("WinGame");

Node.js

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

Egyéni események a Log Analyticsben

A telemetria az customEvents Application Insights Naplók lapján vagy a használati felületen található táblázatban érhető el. Előfordulhat, hogy az események a trackEvent(..) vagy a Click Analytics adatgyűjtő beépülő modulból 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.

Mérőszám lekérése

Ha tudni szeretné, hogyan használhatja hatékonyan a hívást a GetMetric() .NET- és .NET Core-alkalmazások helyileg előre összeállított metrikáinak rögzítésére, 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 kell összesíteni egy adott időszakban, mielőtt elküldené őket. Az egyik GetMetric(..) túlterhelést használva kaphat egy metrika objektumot, amely hozzáférést biztosít az SDK előzetes összesítési képességeihez.

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 Application Insights képes olyan metrikákat ábrázolni, 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.

Metrikák Application Insightsba való küldéséhez 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 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 felhívná 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 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 1, és 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 Application Insightsnak, 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);

Jáva

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 Insights Analytics táblájában érhető el. Minden sor egy trackMetric(..) -hoz az alkalmazásban intézett hívást képvisel.

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

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

Jáva

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ásokat startTrackPage és stopTrackPage.

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 mérsz.

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

Nyomonkövetési kérelem

A kiszolgáló SDK a HTTP-kérések naplózására használja a 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 Insights 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 a művelet befejeződik, vagy ha explicit módon meghívja a(z) StopOperation parancsot. 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 Insights .NET SDK-val.

Kérelmek a Log Analyticsben

Az Application Insights 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 Application Insights szolgáltatásba:

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

C#

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

Jáva

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 meghívnia a TrackException-et.

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

Kivételek a Log Analyticsben

Az Application Insights Analyticsben kivételek jelennek meg a exceptions 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 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 details struktúrát szétszedheti, hogy további információkat szerezzen. Mivel ez a struktúra dinamikus, érdemes az eredményt a várt típusra leadni. 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

Használja a TrackTrace a problémák diagnosztizálásához úgy, hogy egy "kenyérmorzsa útvonalat" küld az Application Insightsnak. 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 Application Insights Java-ügynök automatikusan átküldi és elküldi a naplókat a portálnak.

C#

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

Jáva

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 Sztringek mapja, amely sztringeket sztringekhez rendel. 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} });

Jáva

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 Insights Analyticsben megjelennek a TrackTrace hívások a traces 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 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ó: A kimenő függőségek nyomon követése az Egyéni műveletek követése az Application Insights .NET SDK-val című szakaszában.

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

Jáva

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 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 nyomkövetés nem fog el.

Ha ki szeretné kapcsolni a standard függőségkövetési modult a C#-ban, szerkessze az ApplicationInsights.config fájlt, és törölje a hivatkozását DependencyCollector.DependencyTrackingTelemetryModule. A Java esetében lásd Adott automatikusan gyűjtött telemetriai adatok letiltása.

Függőségek a Log Analyticsben

Az a hívások megjelennek a trackDependency 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öblí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

Amikor a Flush() terméket használja, a következő mintát javasoljuk:

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

Amikor a FlushAsync()-t használja, ezt a 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.

Jáva

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 csatorna számára.

Feljegyzés

  • A Java és JavaScript SDK-k automatikusan kiürítik a beleket az alkalmazás leállításakor.
  • Tekintse át az Automatikus adatáramlás konfigurációját: Az automatikus adatbetöltés engedélyezése a web.config fájlban teljesítménycsökkenéshez vezethet az Application Insights használatával létrehozott .NET-alkalmazásokban. Ha az automatikus adatbetöltés engedélyezve van, a metódusok minden meghívása System.Diagnostics.Trace.Trace* azt eredményezi, hogy az egyes telemetriai elemek külön külön webes kérésként lesznek elküldve a betöltési szolgáltatásnak. Ez hálózati és tárolási kimerültséget okozhat a webkiszolgálókon. A nagyobb teljesítmény érdekében ajánlott letiltani az automatikus adatáramlást, és a Hatékonyabb telemetriai adatátvitelhez tervezett ServerTelemetryChannelt is használni.

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 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ésazonosítójaként a felhasználónév injektálásához szükséges 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.

Azoknál a JavaScript-alkalmazásoknál, amelyek nem úgy működnek, mint az ASP.NET Core MVC, például az SPA-webalkalmazások, manuálisan kell hozzáadnia a appInsights.setAuthenticatedUserContext elemet.

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 karakterlánc hossza legfeljebb 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)

Jáva

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:

  • Ha kiolvas egy értéket a JSON-ból customDimensions vagy customMeasurements, az dinamikus típussal rendelkezik, ezért azt típusra kell alakítania tostring vagy todouble.
  • Annak érdekében, hogy figyelembe vegyük a mintavétel lehetőségét, használja , és ne sum(itemCount).

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

Jáva

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

Jáva

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 mintavételezése, szűrése és feldolgozása

Tekintse meg az Application Insights SDK szűrő- és előfeldolgozási telemetriáját.

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;

Jáva

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 ApplicationInsights.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 telemetria adatokat felgyorsítja a folyamatban, 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 élő környezetben, mert lelassulhat az alkalmazás.

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 instrumentációs kulcsának beállítása

C#

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

Dinamikus műszerkulcs

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 Application Insights-erőforrásokat, és a környezettől függően módosíthatja a kulcsokat.

Ahelyett, hogy az instrumentációs kulcsot a konfigurációs fájlból kérné le, megadhatja 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;

Weboldalak esetében érdemes lehet úgy beállítani, hogy a webkiszolgáló állapota alapján történjen, ahelyett, hogy szó szerint belekódolná a szkriptbe. 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);
    }

Távérzékelési_környezet

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 ApplicationInsights.config fájlbó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 Application Insights-erőforrás az Azure-ban, ahol megjelenik a telemetria. Általában onnan szedik 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 határ 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: .
Korlátozá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 egy erőforrás a naplók számára.
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 tárolása 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 karakterlánc 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.
A rendelkezésre állási tesztek száma Application Insights-erőforrásonként 100 100
Rendelkezésre állási tesztek száma erőforráscsoportonként nyolcszáz nyolcszáz Lásd: Azure Resource Manager
A rendelkezésre állási tesztek maximális átirányítása tesztenként 10 10
Rendelkezésre állási tesztek minimális tesztelési gyakorisága 300 másodperc Az 5 percnél rövidebb egyéni tesztelési gyakoriságok vagy frekvenciák egyéni TrackAvailability implementációt igényelnek.
.NET Profiler és Snapshot Debugger adatmegőrzés Két hét Kapcsolatfelvétel az ügyfélszolgálattal. A maximális megőrzési korlát hat hónap.
Naponta küldött .NET Profiler-adatok Korlátlan Nincs korlát.
Pillanatkép-hibakereső naponta küldött adatai 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ásról és a kvótákról további információt az Application Insights számlázásában talál.

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

Következő lépések