Delen via

Application Insights-API voor aangepaste gebeurtenissen en metrische gegevens

Let op

We raden de Azure Monitor OpenTelemetry Distro aan voor nieuwe toepassingen of klanten om Azure Monitor Application Insights mogelijk te maken. De Azure Monitor OpenTelemetry Distro biedt een vergelijkbare functionaliteit en ervaring als de Application Insights SDK. Het is mogelijk om te migreren van de Application Insights SDK met behulp van de migratiehandleidingen voor .NET, Node.js en Python, maar we werken nog steeds aan het toevoegen van een aantal functies voor achterwaartse compatibiliteit.

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 verwerking van instrumentatiekiesleutels. Verwerking van instrumentatiesleutels blijft werken, maar we bieden geen updates of ondersteuning meer voor de functie. Overgang naar verbindingsreeksen om gebruik te maken 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, vensters 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 Het vastleggen van uitzonderingen voor diagnose. 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 logberichten 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 referentie naar de Application Insights SDK hebt:

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 uit de container voor afhankelijkheidsinjectie, zoals uitgelegd in hun respectieve documentatie.

Als u Azure Functions v2+ of Azure WebJobs v3+ gebruikt, zie Azure Functions monitoren.

C#

private TelemetryClient telemetry = new TelemetryClient();

Als u een bericht ziet dat deze methode is verouderd, raadpleegt u microsoft/ApplicationInsights-dotnet#1152 voor verdere 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 TrackMetric twee keer bellen. 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 met metrieke gegevens werkt, is zelden elke afzonderlijke meting 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 naar trackMetric(..) in 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

Telemetrie van paginaweergaven wordt standaard verzonden in een apparaat- of webpagina-app wanneer een scherm of 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 tijdmetingen voor paginaweergave startTrackPage 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 wilt timen.

Pagina-telemetrie 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, combineer deze dan met de afhankelijkheden.

pageViews
| join (dependencies) on operation_Id

Volgverzoek

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 operationele reikwijdte worden gemeld, worden subitems van een dergelijke bewerking. Bewerkingscontexten kunnen in elkaar geschoven worden.

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:

  • Om ze te 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.

Kenmerk Beschrijving
message Diagnostische gegevens. Kan veel langer zijn dan een naam.
properties Map van tekenreeks naar 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 in de TrackTrace tabel weergegeven.

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 oproep als u oproepen wilt bijhouden die niet worden opgevangen 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. Voor Java, zie onderdrukken van specifieke automatisch verzamelde telemetrie.

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 single-page applications (SPA) webapps, moet u appInsights.setAuthenticatedUserContext nog steeds handmatig toevoegen.

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.
  • Om rekening te houden met de mogelijkheid van steekproeven, gebruik sum(itemCount) niet count().

Tijdgebeurtenissen

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;

Om geselecteerde standaardcollectoren uit te schakelen, zoals prestatiecounters, HTTP-aanvragen of afhankelijkheden, kunt u tijdens de initiatie ketenconfiguratiemethoden 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 het uit in de productieomgeving omdat het uw app kan vertragen.

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 maxBatchSize0in 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 instrumentensleutel

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

TelemetrieContext

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.
  • Operatie: In web-apps is de huidige HTTP-aanvraag. 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 deze niet null of leeg is, is het een tekenreeks die aangeeft dat de bron van het verzoek wordt geïdentificeerd als een 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.

Bron 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.
Snelheidsbeperking 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 Dit hulpmiddel is voor Metrics Explorer.
Beschikbaarheid details over retentie van resultaten van multistep-test 90 dagen 90 dagen Deze resource biedt gedetailleerde resultaten van elke stap.
Maximale grootte van telemetrie-item 64 kB 64 kB
Maximumaantal telemetriegegevens per batch 64,000 64,000
Lengte van eigenschaps- en metrieknaam 150 150 Raadpleeg typeschema's.
Lengte van de eigenschapswaardetekenreeks 8.192 8.192 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 Achthonderd Achthonderd Zie Azure Resource Manager
Maximale omleidingen per test voor beschikbaarheidstests 10 10
Minimale testfrequentie voor beschikbaarheidstests 300 seconden Aangepaste testfrequenties of frequenties van minder dan 5 minuten vereisen aangepaste TrackAvailability-implementaties.
Gegevensretentie van .NET Profiler en Snapshot Debugger Twee weken Neem contact op met ondersteuning. De maximale retentielimiet is zes maanden.
.NET Profiler-gegevens verzonden per dag Geen limiet Geen limiet.
Snapshot Debugger gegevens 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.

Naslagdocumenten

SDK-code

Volgende stappen