Delen via

Application Insights-API voor aangepaste gebeurtenissen en metrische gegevens

  • Artikel

Voeg een paar regels code in uw toepassing in om erachter te komen wat gebruikers ermee doen of om problemen vast te stellen. U kunt telemetrie verzenden vanuit apparaat- en bureaublad-apps, webclients en webservers. Gebruik de Application Insights-kerntelemetrie-API om aangepaste gebeurtenissen en metrische gegevens en uw eigen versies van standaardtelemetrie te verzenden. Deze API is dezelfde API die door de standaard Application Insights-gegevensverzamelaars wordt gebruikt.

Notitie

Op 31 maart 2025 eindigt de ondersteuning voor opname van instrumentatiesleutels. Opname van instrumentatiesleutels blijft werken, maar we bieden geen updates of ondersteuning meer voor de functie. Overgang naar verbindingsreeks s om te profiteren van nieuwe mogelijkheden.

API-overzicht

De kern-API is uniform op alle platforms, afgezien van enkele variaties zoals GetMetric (alleen.NET).

Wijze Gebruikt voor
TrackPageView Pagina's, schermen, deelvensters of formulieren.
TrackEvent Gebruikersacties en andere gebeurtenissen. Wordt gebruikt om gebruikersgedrag bij te houden of om de prestaties te bewaken.
GetMetric Nul en multidimensionale metrische gegevens, centraal geconfigureerde aggregatie, alleen C#.
TrackMetric Prestatiemetingen, zoals wachtrijlengten die niet zijn gerelateerd aan specifieke gebeurtenissen.
TrackException Uitzonderingen voor diagnose vastleggen. Traceer waar ze zich voordoen ten opzichte van andere gebeurtenissen en onderzoek stacktraceringen.
TrackRequest Logboekregistratie van de frequentie en duur van serveraanvragen voor prestatieanalyse.
TrackTrace Diagnostische logboekberichten voor resources. U kunt ook logboeken van derden vastleggen.
TrackDependency Logboekregistratie van de duur en frequentie van aanroepen naar externe onderdelen waarvan uw app afhankelijk is.

U kunt eigenschappen en metrische gegevens koppelen aan de meeste van deze telemetriegesprekken.

Voordat u begint

Als u nog geen verwijzing hebt in Application Insights SDK:

Een TelemetryClient-exemplaar ophalen

Een exemplaar ophalen van TelemetryClient (behalve in JavaScript op webpagina's):

Voor ASP.NET Core-apps en niet-HTTP/Worker voor .NET/.NET Core-apps haalt u een exemplaar van TelemetryClient de container voor afhankelijkheidsinjectie op, zoals wordt uitgelegd in hun respectieve documentatie.

Als u Azure Functions v2+ of Azure WebJobs v3+ gebruikt, raadpleegt u Azure Functions bewaken.

C#

private TelemetryClient telemetry = new TelemetryClient();

Als u een bericht ziet dat deze methode verouderd is, raadpleegt u microsoft/ApplicationInsights-dotnet#1152 voor meer informatie.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient is thread veilig.

Voor ASP.NET- en Java-projecten worden binnenkomende HTTP-aanvragen automatisch vastgelegd. Mogelijk wilt u meer exemplaren maken van TelemetryClient voor andere modules van uw app. U hebt bijvoorbeeld één TelemetryClient exemplaar in uw middlewareklasse om bedrijfslogicagebeurtenissen te rapporteren. U kunt eigenschappen instellen, zoals UserId en DeviceId om de machine te identificeren. Deze informatie wordt gekoppeld aan alle gebeurtenissen die door het exemplaar worden verzonden.

C#

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

Java

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

In Node.js projecten kunt u een nieuw exemplaar maken new applicationInsights.TelemetryClient(instrumentationKey?) . We raden deze benadering alleen aan voor scenario's waarvoor geïsoleerde configuratie van de singleton defaultClientis vereist.

TrackEvent

In Application Insights is een aangepaste gebeurtenis een gegevenspunt dat u in Metrics Explorer kunt weergeven als een geaggregeerd aantal en in Diagnostische zoekopdrachten als afzonderlijke exemplaren. (Het is niet gerelateerd aan MVC of andere framework -gebeurtenissen.)

Voeg TrackEvent aanroepen in uw code in om verschillende gebeurtenissen te tellen. U kunt bijvoorbeeld bijhouden hoe vaak gebruikers een bepaalde functie kiezen. Of misschien wilt u weten hoe vaak ze bepaalde doelen bereiken of specifieke soorten fouten maken.

Verzend bijvoorbeeld in een game-app een gebeurtenis wanneer een gebruiker het spel wint:

JavaScript

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

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

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

Aangepaste gebeurtenissen in Log Analytics

De telemetrie is beschikbaar in de customEvents tabel op het tabblad Application Insights-logboeken of de gebruikservaring. Gebeurtenissen kunnen afkomstig zijn van trackEvent(..) of de invoegtoepassing Click Analytics Auto-collection.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackEvent(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal aangepaste gebeurtenissen wilt ophalen, gebruikt u code zoals customEvents | summarize sum(itemCount).

Notitie

itemCount heeft een minimumwaarde van één; de record zelf vertegenwoordigt een vermelding.

GetMetric

Zie Aangepaste metrische gegevensverzameling in .NET en .NET Core voor meer informatie over het effectief gebruik van de GetMetric() aanroep om lokaal geaggregeerde metrische gegevens vast te leggen voor .NET- en .NET Core-toepassingen.

TrackMetric

Notitie

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric is niet de voorkeursmethode voor het verzenden van metrische gegevens. Metrische gegevens moeten altijd vooraf worden samengevoegd gedurende een bepaalde periode voordat ze worden verzonden. Gebruik een van de GetMetric(..) overbelastingen om een metrisch object op te halen voor toegang tot vooraf aggregatiemogelijkheden voor SDK.

Als u uw eigen vooraggregatielogica implementeert, kunt u de TrackMetric() methode gebruiken om de resulterende aggregaties te verzenden. Als uw toepassing voor elke gelegenheid een afzonderlijk telemetrie-item moet verzenden zonder aggregatie in de tijd, hebt u waarschijnlijk een use-case voor gebeurtenistelemetrie. Zie TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights kan metrische gegevens weergeven die niet zijn gekoppeld aan bepaalde gebeurtenissen. U kunt bijvoorbeeld een wachtrijlengte met regelmatige tussenpozen bewaken. Met metrische gegevens zijn de afzonderlijke metingen minder interessant dan de variaties en trends, en dus zijn statistische grafieken nuttig.

Als u metrische gegevens naar Application Insights wilt verzenden, kunt u de TrackMetric(..) API gebruiken. Er zijn twee manieren om een metrische waarde te verzenden:

  • Eén waarde. Telkens wanneer u een meting uitvoert in uw toepassing, verzendt u de bijbehorende waarde naar Application Insights.

    Stel dat u een metrische waarde hebt die het aantal items in een container beschrijft. Tijdens een bepaalde periode plaatst u eerst drie items in de container en vervolgens verwijdert u twee items. Daarom zou u twee keer bellen TrackMetric . Eerst geeft u de waarde 3 door en geeft u vervolgens de waarde -2door. In Application Insights worden beide waarden voor u opgeslagen.

  • Aggregatie. Wanneer u metrische gegevens werkt, is elke meting zelden van belang. In plaats daarvan is een samenvatting van wat er is gebeurd tijdens een bepaalde periode belangrijk. Een dergelijke samenvatting wordt aggregatie genoemd.

    In het voorgaande voorbeeld is 1 de geaggregeerde metrische som voor die periode en het aantal metrische waarden 2. Wanneer u de aggregatiebenadering gebruikt, roept TrackMetric u slechts één keer per periode aan en verzendt u de geaggregeerde waarden. We raden deze aanpak aan omdat deze de kosten en prestatieoverhead aanzienlijk kan verminderen door minder gegevenspunten naar Application Insights te verzenden, terwijl alle relevante informatie nog steeds wordt verzameld.

Voorbeelden van één waarde

Eén metrische waarde verzenden:

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

Aangepaste metrische gegevens in Log Analytics

De telemetrie is beschikbaar in de customMetrics tabel in Application Insights Analytics. Elke rij vertegenwoordigt een aanroep in trackMetric(..) uw app.

  • valueSum: De som van de metingen. Als u de gemiddelde waarde wilt ophalen, deelt u door valueCount.
  • valueCount: Het aantal metingen dat in deze trackMetric(..) aanroep is samengevoegd.

Notitie

valueCount heeft een minimumwaarde van één; de record zelf vertegenwoordigt een vermelding.

Paginaweergaven

In een apparaat- of webpagina-app wordt telemetrie van paginaweergaven standaard verzonden wanneer elk scherm of elke pagina wordt geladen. Maar u kunt de standaardinstelling wijzigen om paginaweergaven op meer of verschillende tijdstippen bij te houden. In een app met tabbladen of deelvensters kunt u bijvoorbeeld een pagina bijhouden wanneer de gebruiker een nieuw deelvenster opent.

Gebruikers- en sessiegegevens worden verzonden als eigenschappen, samen met paginaweergaven, zodat de gebruikers- en sessiegrafieken tot leven komen wanneer er telemetriegegevens over de paginaweergave zijn.

Aangepaste paginaweergaven

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Als u verschillende tabbladen binnen verschillende HTML-pagina's hebt, kunt u ook de URL opgeven:

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

Tijdspaginaweergaven

De tijden die worden gerapporteerd als laadtijd van de paginaweergave, worden standaard gemeten vanaf wanneer de browser de aanvraag verzendt totdat de gebeurtenis voor het laden van de pagina wordt aangeroepen.

In plaats daarvan kunt u het volgende doen:

  • Stel een expliciete duur in de trackPageView-aanroep in: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Gebruik de tijdsinstellingen van startTrackPage de paginaweergave en stopTrackPage.

JavaScript

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

...

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

De naam die u als eerste parameter gebruikt, koppelt de aanroepen voor starten en stoppen. Deze wordt standaard ingesteld op de naam van de huidige pagina.

De resulterende laadduur van pagina's die worden weergegeven in Metrics Explorer, zijn afgeleid van het interval tussen het starten en stoppen van aanroepen. Het is aan jou welk interval je eigenlijk tijd hebt.

Paginatelemetrie in Log Analytics

In Log Analytics worden in twee tabellen gegevens uit browserbewerkingen weergegeven:

  • pageViews: bevat gegevens over de URL en paginatitel.
  • browserTimings: bevat gegevens over clientprestaties, zoals de tijd die nodig is om de binnenkomende gegevens te verwerken.

Ga als volgt te werk om te zien hoe lang het duurt voordat de browser verschillende pagina's verwerkt:

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

De populariteit van verschillende browsers ontdekken:

pageViews
| summarize count() by client_Browser

Als u paginaweergaven wilt koppelen aan AJAX-aanroepen, voegt u zich samen met afhankelijkheden:

pageViews
| join (dependencies) on operation_Id

TrackRequest

De server-SDK gebruikt TrackRequest om HTTP-aanvragen te registreren.

U kunt deze ook zelf aanroepen als u aanvragen wilt simuleren in een context waarin de webservicemodule niet wordt uitgevoerd.

De aanbevolen manier om aanvraagtelemetrie te verzenden, is waar de aanvraag fungeert als een bewerkingscontext.

Bewerkingscontext

U kunt telemetrie-items aan elkaar correleren door ze te koppelen aan de bewerkingscontext. De standaardmodule voor het bijhouden van aanvragen doet dit voor uitzonderingen en andere gebeurtenissen die worden verzonden terwijl een HTTP-aanvraag wordt verwerkt. In Search and Analytics kunt u eenvoudig gebeurtenissen vinden die zijn gekoppeld aan de aanvraag met behulp van de bewerkings-id.

Zie Telemetriecorrelatie in Application Insights voor meer informatie over correlatie.

Wanneer u telemetrie handmatig bijhoudt, is de eenvoudigste manier om ervoor te zorgen dat telemetriecorrelatie dit patroon gebruikt:

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.

Naast het instellen van een bewerkingscontext, StartOperation maakt u een telemetrie-item van het type dat u opgeeft. Het telemetrie-item wordt verzonden wanneer u de bewerking hebt verwijderd of als u expliciet aanroept StopOperation. Als u als telemetrietype gebruikt RequestTelemetry , wordt de duur ervan ingesteld op het tijdsinterval tussen het begin en einde.

Telemetrie-items die binnen een bewerkingsbereik worden gerapporteerd, worden onderliggende items van een dergelijke bewerking. Bewerkingscontexten kunnen worden genest.

In Search wordt de bewerkingscontext gebruikt om de lijst Gerelateerde items te maken.

Schermopname van de lijst Gerelateerde items.

Zie Aangepaste bewerkingen bijhouden met Application Insights .NET SDK voor meer informatie over het bijhouden van aangepaste bewerkingen.

Aanvragen in Log Analytics

In Application Insights Analytics worden aanvragen weergegeven in de requests tabel.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackRequest(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal aanvragen en de gemiddelde duur wilt ophalen die is gesegmenteerd op aanvraagnamen, gebruikt u code zoals:

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

TrackException

Uitzonderingen verzenden naar Application Insights:

  • Als u ze wilt tellen, als indicatie van de frequentie van een probleem.
  • Afzonderlijke exemplaren onderzoeken.

De rapporten bevatten de stacktraceringen.

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

De SDK's vangen automatisch veel uitzonderingen op, dus u hoeft niet altijd expliciet aan te roepen TrackException :

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

Uitzonderingen in Log Analytics

In Application Insights Analytics worden uitzonderingen weergegeven in de exceptions tabel.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackException(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal uitzonderingen wilt ophalen dat is gesegmenteerd op type uitzondering, gebruikt u code zoals:

exceptions
| summarize sum(itemCount) by type

De meeste belangrijke stackgegevens worden al geëxtraheerd in afzonderlijke variabelen, maar u kunt de details structuur uit elkaar trekken om meer te krijgen. Omdat deze structuur dynamisch is, moet u het resultaat casten naar het type dat u verwacht. Voorbeeld:

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

Als u uitzonderingen aan hun gerelateerde aanvragen wilt koppelen, gebruikt u een join:

exceptions
| join (requests) on operation_Id

TrackTrace

Gebruik TrackTrace dit om problemen te diagnosticeren door een 'breadcrumb trail' naar Application Insights te verzenden. U kunt segmenten met diagnostische gegevens verzenden en inspecteren in Diagnostisch zoeken.

Gebruik deze API in .NET-logboekadapters om logboeken van derden naar de portal te verzenden.

In Java worden met de Java-agent van Application Insights automatisch logboeken verzameld en verzonden naar de portal.

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

JavaScript aan client-/browserzijde

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

Een diagnostische gebeurtenis registreren, zoals het invoeren of verlaten van een methode.

Parameter Description
message Diagnostische gegevens. Kan veel langer zijn dan een naam.
properties Toewijzing van tekenreeks aan tekenreeks. Er worden meer gegevens gebruikt om uitzonderingen in de portal te filteren. De standaardwaarde is leeg.
severityLevel Ondersteunde waarden: SeverityLevel.ts.

U kunt zoeken op berichtinhoud, maar in tegenstelling tot eigenschapswaarden kunt u er niet op filteren.

De limiet voor de grootte message is veel hoger dan de limiet voor eigenschappen. Een voordeel hiervan TrackTrace is dat u relatief lange gegevens in het bericht kunt plaatsen. U kunt bijvoorbeeld POST-gegevens daar coderen.

U kunt ook een ernstniveau toevoegen aan uw bericht. En net als andere telemetrie kunt u eigenschapswaarden toevoegen om u te helpen bij het filteren of zoeken naar verschillende sets traceringen. Voorbeeld:

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

In Zoeken kunt u vervolgens eenvoudig alle berichten van een bepaald ernstniveau filteren die betrekking hebben op een bepaalde database.

Traceringen in Log Analytics

In Application Insights Analytics worden aanroepen weergegeven TrackTrace in de traces tabel.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackTrace(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal traceringsoproepen wilt ophalen, gebruikt u code zoals traces | summarize sum(itemCount).

TrackDependency

Gebruik de TrackDependency aanroep om de reactietijden en slagingspercentages van aanroepen naar een extern codefragment bij te houden. De resultaten worden weergegeven in de afhankelijkheidsdiagrammen in de portal. Het volgende codefragment moet worden toegevoegd waar een afhankelijkheidsaanroep wordt gedaan.

Notitie

Voor .NET en .NET Core kunt u ook de TelemetryClient.StartOperation methode (extensie) gebruiken waarmee de DependencyTelemetry eigenschappen worden ingevuld die nodig zijn voor correlatie en enkele andere eigenschappen, zoals de begintijd en duur, zodat u geen aangepaste timer hoeft te maken zoals in de volgende voorbeelden. Zie de sectie over het bijhouden van uitgaande afhankelijkheid in Aangepaste bewerkingen bijhouden met Application Insights .NET SDK voor meer informatie.

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

Houd er rekening mee dat de server-SDK's een afhankelijkheidsmodule bevatten waarmee bepaalde afhankelijkheidsaanroepen automatisch worden gedetecteerd en bijgehouden, bijvoorbeeld naar databases en REST API's. U moet een agent op uw server installeren om de module te laten werken.

In Java kunnen veel afhankelijkheidsaanroepen automatisch worden bijgehouden met behulp van de Application Insights Java-agent.

U gebruikt deze aanroep als u aanroepen wilt bijhouden die niet worden onderscheppen door automatische tracering.

Als u de standaardmodule voor het bijhouden van afhankelijkheden in C# wilt uitschakelen, bewerkt u ApplicationInsights.config en verwijdert u de verwijzing naar DependencyCollector.DependencyTrackingTelemetryModule. Zie Voor Java specifieke automatisch opgehaalde telemetrie onderdrukken.

Afhankelijkheden in Log Analytics

In Application Insights AnalyticstrackDependency worden aanroepen weergegeven in de dependencies tabel.

Als er steekproeven worden genomen , wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackDependency(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal afhankelijkheden wilt ophalen dat per doelonderdeel is gesegmenteerd, gebruikt u code zoals:

dependencies
| summarize sum(itemCount) by target

Als u afhankelijkheden wilt koppelen aan hun gerelateerde aanvragen, gebruikt u een join:

dependencies
| join (requests) on operation_Id

Gegevens leegmaken

Normaal gesproken verzendt de SDK gegevens met vaste intervallen, meestal 30 seconden of wanneer de buffer vol is, wat meestal 500 items is. In sommige gevallen wilt u de buffer mogelijk leegmaken. Een voorbeeld is als u de SDK gebruikt in een toepassing die wordt afgesloten.

.NET

Wanneer u gebruikt Flush(), raden we dit patroon aan:

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

Wanneer u gebruikt FlushAsync(), raden we dit patroon aan:

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

We raden u aan altijd leeg te maken als onderdeel van het afsluiten van de toepassing om ervoor te zorgen dat telemetrie niet verloren gaat.

Java

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

Node.js

telemetry.flush();

De functie is asynchroon voor het telemetriekanaal van de server.

Notitie

  • De Java- en JavaScript SDK's worden automatisch leeggemaakt bij het afsluiten van de toepassing.
  • Controleer de autoflush-configuratie: als u autoflush inschakelt in uw web.config bestand, kan dit leiden tot prestatievermindering in .NET-toepassingen die zijn geïnstrueerd met Application Insights. Als autoflush is ingeschakeld, resulteert elke aanroep van System.Diagnostics.Trace.Trace* methoden in afzonderlijke telemetrie-items die als afzonderlijke afzonderlijke webaanvragen worden verzonden naar de opnameservice. Dit kan leiden tot netwerk- en opslaguitputting op uw webservers. Voor verbeterde prestaties is het raadzaam om autoflush uit te schakelen en ook de ServerTelemetryChannel te gebruiken, ontworpen voor een effectievere telemetriegegevensoverdracht.

Geverifieerde gebruikers

In een web-app worden gebruikers standaard geïdentificeerd door cookies . Een gebruiker kan meerdere keren worden geteld als hij of zij toegang heeft tot uw app vanaf een andere computer of browser of als ze cookies verwijderen.

Als gebruikers zich aanmelden bij uw app, kunt u een nauwkeuriger aantal krijgen door de geverifieerde gebruikers-id in te stellen in de browsercode:

JavaScript

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

In een ASP.NET web-MVC-toepassing, bijvoorbeeld:

Scheermes

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

Het is niet nodig om de werkelijke aanmeldingsnaam van de gebruiker te gebruiken. Het hoeft alleen een id te zijn die uniek is voor die gebruiker. Het mag geen spaties of een van de tekens ,;=|bevatten.

De gebruikers-id wordt ook ingesteld in een sessiecooky en verzonden naar de server. Als de server-SDK is geïnstalleerd, wordt de geverifieerde gebruikers-id verzonden als onderdeel van de contexteigenschappen van zowel client- als servertelemetrie. Vervolgens kunt u erop filteren en zoeken.

Als uw app gebruikers in accounts groepeert, kunt u ook een id voor het account doorgeven. Dezelfde tekenbeperkingen gelden.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

In Metrics Explorer kunt u een grafiek maken waarmee gebruikers, geverifieerde en gebruikersaccounts worden geteld.

U kunt ook zoeken naar clientgegevenspunten met specifieke gebruikersnamen en accounts.

Notitie

De eigenschap EnableAuthenticationTrackingJavaScript in de klasse ApplicationInsightsServiceOptions in de .NET Core SDK vereenvoudigt de JavaScript-configuratie die nodig is om de gebruikersnaam in te voeren als de verificatie-id voor elke trace die wordt verzonden door de Application Insights JavaScript SDK.

Wanneer deze eigenschap is ingesteld op true, wordt de gebruikersnaam van de gebruiker in de ASP.NET Core samen met telemetrie aan de clientzijde afgedrukt. Daarom is het handmatig toevoegen appInsights.setAuthenticatedUserContext niet meer nodig omdat deze al door de SDK is geïnjecteerd voor ASP.NET Core. De verificatie-id wordt ook verzonden naar de server waar de SDK in .NET Core deze identificeert en gebruikt voor telemetrie aan de serverzijde, zoals beschreven in de JavaScript-API-verwijzing.

Voor JavaScript-toepassingen die niet op dezelfde manier werken als ASP.NET Core MVC, zoals beveiligd-WACHTWOORDVERIFICATIE-web-apps, moet u nog steeds handmatig toevoegen appInsights.setAuthenticatedUserContext .

Uw gegevens filteren, zoeken en segmenteren met behulp van eigenschappen

U kunt eigenschappen en metingen koppelen aan uw gebeurtenissen, metrische gegevens, paginaweergaven, uitzonderingen en andere telemetriegegevens.

Eigenschappen zijn tekenreekswaarden die u kunt gebruiken om uw telemetrie in de gebruiksrapporten te filteren. Als uw app bijvoorbeeld verschillende games biedt, kunt u de naam van het spel koppelen aan elke gebeurtenis, zodat u kunt zien welke games populairder zijn.

Er geldt een limiet van 8.192 voor de tekenreekslengte. Als u grote stukken gegevens wilt verzenden, gebruikt u de berichtparameter van TrackTrace.

Metrische gegevens zijn numerieke waarden die grafisch kunnen worden weergegeven. U kunt bijvoorbeeld zien of er een geleidelijke toename is van de scores die uw gamers behalen. De grafieken kunnen worden gesegmenteerd door de eigenschappen die met de gebeurtenis worden verzonden, zodat u afzonderlijke of gestapelde grafieken voor verschillende games kunt krijgen.

Metrische waarden moeten groter zijn dan of gelijk zijn aan 0 om correct weer te geven.

Er gelden enkele limieten voor het aantal eigenschappen, eigenschapswaarden en metrische gegevens die u kunt gebruiken.

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

Notitie

Zorg ervoor dat u geen persoonsgegevens in eigenschappen opgeeft.

Alternatieve manier om eigenschappen en metrische gegevens in te stellen

Als het handiger is, kunt u de parameters van een gebeurtenis in een afzonderlijk object verzamelen:

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

Waarschuwing

Gebruik niet hetzelfde exemplaar van het telemetrie-item (event in dit voorbeeld) om meerdere keren aan te roepen Track*() . Deze procedure kan ertoe leiden dat telemetrie wordt verzonden met een onjuiste configuratie.

Aangepaste metingen en eigenschappen in Log Analytics

In Log Analytics worden aangepaste metrische gegevens en eigenschappen weergegeven in de customMeasurements en customDimensions kenmerken van elke telemetrierecord.

Als u bijvoorbeeld een eigenschap met de naam 'game' toevoegt aan uw aanvraagtelemetrie, telt deze query het aantal exemplaren van verschillende waarden van 'game' en toont het gemiddelde van de aangepaste metrische waarde 'score':

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

U ziet dat:

  • Wanneer u een waarde uit de customDimensions of customMeasurements JSON extraheert, heeft deze een dynamisch type, dus moet u deze tostring casten of todouble.
  • Gebruik geen gebruik om rekening te houden met de mogelijkheid van steekproevensum(itemCount).count()

Tijdsinstellingen

Soms wilt u een grafiek maken hoe lang het duurt om een actie uit te voeren. U wilt bijvoorbeeld weten hoelang gebruikers rekening houden met keuzes in een game. Gebruik de meetparameter om deze informatie te verkrijgen.

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

Standaardeigenschappen voor aangepaste telemetrie

Als u standaardeigenschapswaarden wilt instellen voor een aantal van de aangepaste gebeurtenissen die u schrijft, stelt u deze in een TelemetryClient instantie in. Ze worden gekoppeld aan elk telemetrie-item dat vanaf die client wordt verzonden.

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

Afzonderlijke telemetrie-aanroepen kunnen de standaardwaarden in hun eigenschapswoordenlijsten overschrijven.

Voor JavaScript-webclients gebruikt u initialisatiefuncties voor JavaScript-telemetrie.

Als u eigenschappen wilt toevoegen aan alle telemetriegegevens, inclusief de gegevens uit standaardverzamelingsmodules, implementeert u ITelemetryInitializer.

Voorbeeld-, filter- en procestelemetrie

Zie Telemetrie filteren en vooraf verwerken in de Application Insights SDK.

Telemetrie uitschakelen

De verzameling en verzending van telemetrie dynamisch stoppen en starten :

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Als u geselecteerde standaardverzamelaars wilt uitschakelen, bijvoorbeeld prestatiemeteritems, HTTP-aanvragen of afhankelijkheden, verwijdert of markeert u de relevante regels in ApplicationInsights.config. Een voorbeeld is als u uw eigen TrackRequest gegevens wilt verzenden.

Node.js

telemetry.config.disableAppInsights = true;

Als u geselecteerde standaardverzamelaars wilt uitschakelen, bijvoorbeeld prestatiemeteritems, HTTP-aanvragen of afhankelijkheden, kunt u tijdens de initialisatie de configuratiemethoden voor de keten aan uw SDK-initialisatiecode koppelen.

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

Als u deze verzamelaars na initialisatie wilt uitschakelen, gebruikt u het configuratieobject: applicationInsights.Configuration.setAutoCollectRequests(false).

Ontwikkelaarsmodus

Tijdens foutopsporing is het handig om uw telemetrie te laten versnellen via de pijplijn, zodat u direct resultaten kunt zien. U krijgt ook andere berichten waarmee u problemen met de telemetrie kunt traceren. Schakel deze uit in productie omdat uw app mogelijk wordt vertraagd.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Voor Node.js kunt u de ontwikkelaarsmodus inschakelen door interne logboekregistratie via setInternalLogging en instelling maxBatchSize 0in te schakelen, waardoor uw telemetrie wordt verzonden zodra deze wordt verzameld.

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

De instrumentatiesleutel instellen voor geselecteerde aangepaste telemetrie

C#

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

Dynamische instrumentatiesleutel

Om te voorkomen dat telemetrie wordt vermengd vanuit ontwikkel-, test- en productieomgevingen, kunt u afzonderlijke Application Insights-resources maken en hun sleutels wijzigen, afhankelijk van de omgeving.

In plaats van de instrumentatiesleutel op te halen uit het configuratiebestand, kunt u deze instellen in uw code. Stel de sleutel in een initialisatiemethode in, zoals global.aspx.cs in een ASP.NET-service:

C#

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

JavaScript

appInsights.config.instrumentationKey = myKey;

In webpagina's wilt u deze mogelijk instellen vanuit de status van de webserver in plaats van deze letterlijk in het script te coderen. Bijvoorbeeld op een webpagina die is gegenereerd in een ASP.NET-app:

JavaScript in Razor

<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 heeft een contexteigenschap, die waarden bevat die samen met alle telemetriegegevens worden verzonden. Ze worden normaal gesproken ingesteld door de standaardtelemetriemodules, maar u kunt ze ook zelf instellen. Voorbeeld:

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

Als u een van deze waarden zelf instelt, kunt u overwegen om de relevante regel uit ApplicationInsights.config te verwijderen, zodat uw waarden en de standaardwaarden niet in de war raken.

  • Onderdeel: de app en de bijbehorende versie.
  • Apparaat: gegevens over het apparaat waarop de app wordt uitgevoerd. In web-apps is het de server of het clientapparaat waaruit de telemetrie wordt verzonden.
  • InstrumentationKey: de Application Insights-resource in Azure waar de telemetrie wordt weergegeven. Het wordt meestal opgehaald van ApplicationInsights.config.
  • Locatie: De geografische locatie van het apparaat.
  • Bewerking: In web-apps wordt de huidige HTTP-aanvraag gebruikt. In andere app-typen kunt u deze waarde instellen om gebeurtenissen samen te groeperen.
    • Id: Een gegenereerde waarde die verschillende gebeurtenissen correleert, zodat u gerelateerde items kunt vinden wanneer u een gebeurtenis inspecteert in diagnostische zoekopdrachten.
    • Naam: een id, meestal de URL van de HTTP-aanvraag.
    • SyntheticSource: Als dit niet null of leeg is, wordt een tekenreeks die aangeeft dat de bron van de aanvraag is geïdentificeerd als robot of webtest. Standaard wordt deze uitgesloten van berekeningen in Metrics Explorer.
  • Sessie: de sessie van de gebruiker. De id wordt ingesteld op een gegenereerde waarde, die wordt gewijzigd wanneer de gebruiker al een tijdje niet actief is geweest.
  • Gebruiker: Gebruikersgegevens.

Limieten

Er gelden enkele beperkingen voor het aantal meetgegevens en gebeurtenissen per toepassing, per instrumentatiesleutel. De limieten zijn afhankelijk van de prijscategorie die u kiest.

Resource Standaardlimiet Bovengrens Opmerkingen
Totale hoeveelheid gegevens per dag 100 GB Neem contact op met ondersteuning. U kunt een limiet instellen om gegevens te verminderen. Als u meer gegevens nodig hebt, kunt u de limiet in de portal verhogen tot 1000 GB. Voor capaciteiten groter dan 1000 GB stuurt u een mail naar AIDataCap@microsoft.com.
Beperking 32.000 gebeurtenissen per seconde Neem contact op met ondersteuning. De limiet wordt gemeten in een minuut.
Logboeken voor gegevensretentie 30 tot 730 dagen 730 dagen Deze resource is voor logboeken.
Metrische gegevens over gegevensretentie 90 dagen 90 dagen Deze resource is voor Metrics Explorer.
Gedetailleerde retentie van resultaten voor multistep-test voor beschikbaarheid 90 dagen 90 dagen Deze resource biedt gedetailleerde resultaten van elke stap.
Maximale grootte telemetriegegeven 64 kB 64 kB
Maximumaantal telemetriegegevens per batch 64,000 64,000
Naamlengte voor de eigenschappen en meetgegevens 150 150 Raadpleeg typeschema's.
Lengte van de tekenreeks eigenschapswaarde 8192 8192 Raadpleeg typeschema's.
Lengte van berichten voor tracering en uitzonderingen 32.768 32.768 Raadpleeg typeschema's.
Aantal beschikbaarheidstests per Application Insights-resource 100 100
Aantal beschikbaarheidstests per resourcegroep 800 800 Zie Azure Resource Manager
Maximale omleidingen per test voor beschikbaarheidstests 10 10
Minimale testfrequentie voor beschikbaarheidstests 300 seconden Aangepaste testfrequenties of frequenties die minder dan 5 minuten duren, vereisen aangepaste TrackAvailability-implementaties .
Retentie van profiler- en momentopnamegegevens Twee weken Neem contact op met ondersteuning. De maximale retentielimiet is zes maanden.
Verzonden gegevens per dag voor Profiler Geen limiet Geen limiet.
Momentopnamegegevens verzonden per dag 30 momentopnamen per dag per bewaakte app Geen limiet. Het aantal momentopnamen dat per toepassing wordt verzameld, kan worden gewijzigd via de configuratie.

Zie Application Insights-facturering voor meer informatie over prijzen en quota.

Gebruik steekproeven om te voorkomen dat de gegevenssnelheidslimiet wordt bereikt.

Zie Gegevensretentie en privacy om te bepalen hoe lang gegevens worden bewaard.

Naslagdocumentatie

SDK-code

Veelgestelde vragen

In deze sectie vindt u antwoorden op veelgestelde vragen.

Waarom mis ik telemetriegegevens?

Beide TelemetryChannels verliezen gebufferde telemetrie als deze niet wordt leeggemaakt voordat een toepassing wordt afgesloten.

Als u gegevensverlies wilt voorkomen, moet u de TelemetryClient leegmaken wanneer een toepassing wordt afgesloten.

Zie Gegevens leegmaken voor meer informatie.

Welke uitzonderingen kunnen Track_() aanroepen genereren?

Geen. U hoeft ze niet in try-catch-componenten te verpakken. Als de SDK problemen ondervindt, worden er berichten vastgelegd in de uitvoer van de foutopsporingsconsole en, als de berichten binnenkomen, in Diagnostisch zoeken.

Is er een REST API om gegevens op te halen uit de portal?

Ja, de API voor gegevenstoegang. Andere manieren om gegevens te extraheren, zijn Power BI als u bent gemigreerd naar een resource op basis van een werkruimte of continue export als u nog steeds een klassieke resource gebruikt.

Waarom worden mijn aanroepen naar aangepaste gebeurtenissen en api's voor metrische gegevens genegeerd?

De Application Insights SDK is niet compatibel met auto-instrumentatie. Als automatische instrumentatie is ingeschakeld, worden aanroepen naar Track() en andere aangepaste gebeurtenissen en API's voor metrische gegevens genegeerd.

Schakel automatische instrumentatie uit in Azure Portal op het tabblad Application Insights van de App Service-pagina of ingesteld op ApplicationInsightsAgent_EXTENSION_VERSION disabled.

Waarom zijn de aantallen in grafieken Met zoek- en metrische gegevens ongelijk?

Sampling vermindert het aantal telemetrie-items (zoals aanvragen en aangepaste gebeurtenissen) dat vanuit uw app naar de portal wordt verzonden. In Zoeken ziet u het aantal ontvangen items. In metrische grafieken waarin het aantal gebeurtenissen wordt weergegeven, ziet u het aantal oorspronkelijke gebeurtenissen dat is opgetreden.

Elk item dat wordt verzonden, heeft een itemCount eigenschap die laat zien hoeveel oorspronkelijke gebeurtenissen het item vertegenwoordigt. Als u steekproeven in de bewerking wilt bekijken, kunt u deze query uitvoeren in Log Analytics:

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

Hoe kan ik een waarschuwing instellen voor een gebeurtenis?

Azure-waarschuwingen zijn alleen beschikbaar voor metrische gegevens. Maak een aangepaste metrische waarde die een waardedrempel overschrijdt wanneer uw gebeurtenis plaatsvindt. Stel vervolgens een waarschuwing in voor de metrische waarde. U ontvangt een melding wanneer de metrische waarde de drempelwaarde in beide richtingen overschrijdt. U ontvangt geen melding tot de eerste kruising, ongeacht of de initiële waarde hoog of laag is. Er is altijd een latentie van een paar minuten.

Volgende stappen