Application Insights-API voor aangepaste gebeurtenissen en metrische gegevens

Voeg een paar regels code in uw toepassing in om erachter te komen wat gebruikers hiermee doen of om problemen te diagnosticeren. U kunt telemetrie verzenden vanaf apparaat- en desktop-apps, webcl clients en webservers. Gebruik de Azure-toepassing Insights core telemetrie-API om aangepaste gebeurtenissen en metrische gegevens en uw eigen versies van standaard telemetrie te verzenden. Deze API is dezelfde API die de standaard Application Insights-gegevensverzamelaars gebruikt.

API-overzicht

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

U kunt eigenschappen en metrische gegevens koppelen aan de meeste van deze telemetrie-aanroepen.

Voordat u begint

Als u nog geen verwijzing hebt over Application Insights SDK:

• Voeg de Application Insights-SDK toe aan uw project:

  • ASP.NET project
  • ASP.NET Core project
  • Java-project
  • Node.js project
  • JavaScript op elke webpagina

• Neem het volgende op in de code van uw apparaat of webserver:

  C#:using Microsoft.ApplicationInsights;

  Visual Basic:Imports Microsoft.ApplicationInsights

  Java:import com.microsoft.applicationinsights.TelemetryClient;

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

Een TelemetryClient-exemplaar op halen

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

Voor ASP.NET Core-apps en niet-HTTP/Worker voor .NET/.NET Core-apps wordt het aanbevolen om een exemplaar van op te halen uit de container voor afhankelijkheidsinjectie, zoals uitgelegd in de respectieve TelemetryClient documentatie.

Als u AzureFunctions v2+ of Azure WebJobs v3+ gebruikt, volgt u dit document.

C#

private TelemetryClient telemetry = new TelemetryClient();

Als u wilt dat deze methode verouderde berichten is, gaat u naar 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-safe.

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

C#

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

Java

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

In Node.js-projecten kunt u gebruiken om een nieuw exemplaar te maken, maar dit wordt alleen aanbevolen voor scenario's waarvoor een geïsoleerde configuratie van new applicationInsights.TelemetryClient(instrumentationKey?) de singleton is defaultClient vereist.

TrackEvent

In Application Insights is een aangepaste gebeurtenis een gegevenspunt dat u in Metrics Explorer kunt weergeven als een geaggregeerd aantal en in Diagnostic Search als afzonderlijke exemplaren. (Het is niet gerelateerd aan MVC of andere frameworkgebeurtenissen.)

Voeg TrackEvent aanroepen in uw code in om verschillende gebeurtenissen te tellen. Hoe vaak gebruikers een bepaalde functie kiezen, hoe vaak ze bepaalde doelen bereiken of hoe vaak ze bepaalde typen 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 Analytics

De telemetrie is beschikbaar in de customEvents tabel op het tabblad Application Insights Logs of Usage Experience. Gebeurtenissen kunnen afkomstig zijn van trackEvent(..) of klikken op Analytics Auto-collection Plugin.

Als er steekproeven worden genomen, toont de eigenschap itemCount een waarde die groter is dan 1. ItemCount==10 betekent bijvoorbeeld dat van 10 aanroepen naar trackEvent() het steekproefproces er slechts één heeft verzonden. Als u het juiste aantal aangepaste gebeurtenissen wilt weten, moet u daarom code zoals customEvents | summarize sum(itemCount) gebruiken.

GetMetric

Ga naar de GetMetric-documentatie voor meer informatie over het effectief gebruiken van de GetMetric()-aanroep om lokaal vooraf geaggregeerde metrische gegevens voor .NET- en .NET Core-toepassingen vast te leggen.

TrackMetric

Toepassings Insights kunnen metrische gegevens in een grafiek bekijken die niet zijn gekoppeld aan bepaalde gebeurtenissen. U kunt bijvoorbeeld de lengte van een wachtrij met regelmatige intervallen controleren. Met metrische gegevens zijn de afzonderlijke metingen minder interessant dan de variaties en trends, waardoor statistische grafieken nuttig zijn.

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

• Eén waarde. Telkens wanneer u een meting in uw toepassing voert, verzendt u de bijbehorende waarde naar Application Insights. Stel dat u een metrisch getal hebt dat het aantal items in een container beschrijft. Tijdens een bepaalde periode moet u eerst drie items in de container zetten en vervolgens twee items verwijderen. Daarom roept u twee keer TrackMetric aan: eerst de waarde en 3 vervolgens de waarde -2 doorgeven. Toepassings Insights slaat beide waarden namens u op.

• Aggregatie. Bij het werken met metrische gegevens is elke enkele meting zelden van belang. In plaats daarvan is een samenvatting van wat er tijdens een bepaalde periode is gebeurd belangrijk. Een dergelijke samenvatting wordt aggregatie genoemd. In het bovenstaande voorbeeld is de cumulatief metrische som voor die periode en is het 1 aantal van de metrische waarden 2 . Wanneer u de aggregatiebenadering gebruikt, roept u slechts één keer per periode aan en TrackMetric verzendt u de geaggregeerde waarden. Dit is de aanbevolen aanpak omdat de kosten en prestatieoverhead aanzienlijk kunnen worden verminderd door minder gegevenspunten naar Application Insights te verzenden, terwijl nog steeds alle relevante informatie wordt verzameld.

Voorbeelden

Enkele waarden

Eén metrische waarde verzenden:

JavaScript

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

C#

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

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

Aangepaste metrische gegevens in Analytics

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

• valueSum - Dit is de som van de metingen. Als u de gemiddelde waarde wilt op halen, deelt u door valueCount .
• valueCount - Het aantal metingen dat in deze aanroep is trackMetric(..) geaggregeerd.

Paginaweergaven

In een apparaat- of webpagina-app wordt standaard telemetrie verzonden wanneer elk scherm of elke pagina wordt geladen. U kunt dit echter wijzigen om paginaweergaven op extra of verschillende tijdstippen bij te houden. In een app waarin bijvoorbeeld tabbladen of blades worden weergegeven, wilt u mogelijk een pagina bijhouden wanneer de gebruiker een nieuwe blade opent.

Gebruikers- en sessiegegevens worden samen met paginaweergaven als eigenschappen verzonden, zodat de gebruikers- en sessiegrafieken tot leven komen wanneer er telemetriegegevens over paginaweergaven 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");

Paginaweergaven timing

Standaard worden de tijden die worden gerapporteerd als laadtijd van paginaweergave gemeten vanaf het moment dat de browser de aanvraag verzendt, totdat de gebeurtenis pagina laden van de browser 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 timing-aanroepen van de 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. De standaardinstelling is de naam van de huidige pagina.

De resulterende duur van paginabelasting die wordt weergegeven in Metrics Explorer worden afgeleid van het interval tussen de aanroepen voor starten en stoppen. Het is aan u welk interval u daadwerkelijk nodig hebt.

Pagina-telemetrie in Analytics

In Analytics worden in twee tabellen gegevens van browserbewerkingen weergegeven:

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

Als u wilt weten 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, koppelt u aan afhankelijkheden:

pageViews
| join (dependencies) on operation_Id 

TrackRequest

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

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

De aanbevolen manier om aanvraag-telemetrie te verzenden is echter wanneer de aanvraag fungeert als bewerkingscontext.

Bewerkingscontext

U kunt telemetrie-items 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 Analyticskunt u eenvoudig alle gebeurtenissen vinden die aan de aanvraag zijn gekoppeld met behulp van de bewerkings-id.

Zie Telemetriecorrelatie in Application Insights meer informatie over correlatie.

Wanneer u telemetrie handmatig bijwerkt, is dit de eenvoudigste manier om telemetriecorrelatie te garanderen met behulp van dit patroon:

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 maakt StartOperation u een telemetrie-item van het type dat u opgeeft. Hiermee wordt het telemetrie-item verzendt wanneer u de bewerking wilt verwijderen of als u expliciet StopOperation aanroept. Als u als RequestTelemetry het telemetrietype gebruikt, wordt de duur ervan ingesteld op het tijdsinterval tussen starten en stoppen.

Telemetrie-items die binnen het bereik van de bewerking worden gerapporteerd, worden 'kinderen' van een dergelijke bewerking. Bewerkingscontexten kunnen worden genest.

In Zoeken wordt de bewerkingscontext gebruikt om de lijst Gerelateerde items te maken:

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

Aanvragen in Analytics

In Application Insights Analyticsworden aanvragen in de tabel weer requests geven.

Als er steekproeven worden genomen, toont de eigenschap itemCount een waarde die groter is dan 1. ItemCount==10 betekent bijvoorbeeld dat van 10 aanroepen naar trackRequest() het steekproefproces er slechts één heeft verzonden. Als u het juiste aantal aanvragen en de gemiddelde duur wilt weten, 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.
• Om afzonderlijke exemplaren te onderzoeken.

De rapporten bevatten de stack-traces.

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 ondervangen veel uitzonderingen automatisch, zodat u TrackException niet altijd expliciet hoeft aan te roepen.

• ASP.NET: schrijf code om uitzonderingen te ondervangen.
• Java EE: Uitzonderingen worden automatisch af vangen.
• JavaScript: Uitzonderingen worden automatisch af vangen. Als u automatische verzameling wilt uitschakelen, voegt u een regel toe aan het codefragment dat u op uw webpagina's invoegt:

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

Uitzonderingen in Analytics

In Application Insights Analyticsworden uitzonderingen in de tabel weer exceptions geven.

Als er steekproeven worden genomen, toont itemCount de eigenschap een waarde die groter is dan 1. ItemCount==10 betekent bijvoorbeeld dat van 10 aanroepen naar trackException() het steekproefproces er slechts één heeft verzonden. Als u het juiste aantal uitzonderingen wilt weten, gesegmenteerd op type uitzondering, gebruikt u code zoals:

exceptions
| summarize sum(itemCount) by type

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

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

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

exceptions
| join (requests) on operation_Id

TrackTrace

Gebruik TrackTrace om problemen vast te stellen door een 'breadcrumb-trail' naar Application Insights. U kunt segmenten met diagnostische gegevens verzenden en deze inspecteren in Diagnostic Search.

In .NET-logboekadapters gebruikt u deze API om logboeken van derden naar de portal te verzenden.

In Java verzamelt de Application Insights Java-agent automatisch logboeken en verzendt deze 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
})

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

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

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

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

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 Zoekenkunt u vervolgens eenvoudig alle berichten met een bepaald ernstniveau filteren die betrekking hebben op een bepaalde database.

Traceringen in Analytics

In Application Insights Analyticsworden aanroepen naar TrackTrace in de tabel weer traces geven.

Als er steekproeven worden genomen, toont de eigenschap itemCount een waarde die groter is dan 1. ItemCount==10 betekent bijvoorbeeld dat van 10 aanroepen naar , het steekproefproces er slechts één trackTrace() heeft verzonden. Als u een correct aantal traceeroproepen wilt, moet u daarom code zoals traces | summarize sum(itemCount) gebruiken.

TrackDependency

Gebruik de aanroep TrackDependency om de reactietijden en het slagingspercentage van aanroepen naar een extern stuk code bij te houden. De resultaten worden weergegeven in de afhankelijkheidsgrafieken in de portal. Het onderstaande codefragment moet worden toegevoegd waar een afhankelijkheidsoproep wordt gedaan.

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

Vergeet niet dat de server-SDK's een afhankelijkheidsmodule bevatten die bepaalde afhankelijkheidsoproepen automatisch detecteert en bij houdt, 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 afhankelijkheidsoproepen automatisch worden gevolgd met behulp van de Application Insights Java-agent.

U gebruikt deze aanroep als u aanroepen wilt bijhouden die niet worden ondervangen door geautomatiseerde tracering.

Als u de standaardmodule voor het bijhouden van afhankelijkheden in C# wilt uitschakelen, bewerktApplicationInsights.config en verwijdert u de verwijzing naar DependencyCollector.DependencyTrackingTelemetryModule . Zie Specifieke automatisch verzamelde telemetrie onderdrukken voorJava.

Afhankelijkheden in Analytics

In Application Insights Analyticsworden aanroepen van trackDependency in de tabel weer dependencies geven.

Als er steekproeven worden genomen, toont de eigenschap itemCount een waarde die groter is dan 1. ItemCount==10 betekent bijvoorbeeld dat van 10 aanroepen naar trackDependency() het steekproefproces er slechts één heeft verzonden. Als u het juiste aantal afhankelijkheden wilt weten, gesegmenteerd op doelonderdeel, 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 leeg maken

Normaal gesproken verzendt de SDK gegevens met vaste intervallen (meestal 30 seconden) of wanneer de buffer vol is (meestal 500 items). In sommige gevallen wilt u de buffer echter leeg maken, bijvoorbeeld als u de SDK gebruikt in een toepassing die wordt afgesloten.

C#

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

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.

In het ideale moment moet de methode flush() worden gebruikt in de afsluitactiviteit van de toepassing.

Geverifieerde gebruikers

In een web-app worden gebruikers (standaard) geïdentificeerd door cookies. Een gebruiker kan meer dan één keer worden geteld als hij of zij toegang heeft tot uw app vanaf een andere computer of browser, of als deze cookies verwijdert.

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:

Razor

@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. Deze mag geen spaties of een van de tekens ,;=| bevatten.

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

Als uw app gebruikers groepeert in accounts, kunt u ook een id voor het account doorgeven (met dezelfde tekenbeperkingen).

appInsights.setAuthenticatedUserContext(validatedId, accountId);

In Metrics Explorerkunt u een grafiek maken die gebruikers, geverifieerde en gebruikersaccounts telt.

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

Uw gegevens filteren, doorzoeken en segmenteren met behulp van eigenschappen

U kunt eigenschappen en metingen koppelen aan uw gebeurtenissen (en ook aan 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 aan elke gebeurtenis koppelen, zodat u kunt zien welke games populairder zijn.

Er geldt een limiet van 8192 voor de tekenreekslengte. (Als u grote hoeveelheden gegevens wilt verzenden, gebruikt u de berichtparameter van TrackTrace.)

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

Metrische waarden worden alleen correct weergegeven als ze groter zijn dan of gelijk zijn aan 0.

Er zijn enkele limieten voor het aantal eigenschappen, eigenschapswaarden en metrische gegevens dat 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);

Alternatieve manier om eigenschappen en metrische gegevens in te stellen

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

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

Aangepaste metingen en eigenschappen in Analytics

In Analyticsworden aangepaste metrische gegevens en eigenschappen in de customMeasurements kenmerken en van elke customDimensions telemetrierecord weergeven.

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

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

U ziet dat:

• Wanneer u een waarde uit de JSON customDimensions of customMeasurements extraheert, heeft deze een dynamisch type en moet u deze casten tostring of todouble .
• Als u rekening wilt houden met de mogelijkheid om steekproeven tenemen, moet u sum(itemCount) gebruiken, niet count() .

Timinggebeurtenissen

Soms wilt u in kaart brengen hoe lang het duurt om een actie uit te voeren. U wilt bijvoorbeeld weten hoe lang gebruikers nodig hebben om keuzes in een spel te overwegen. U kunt hiervoor de meetparameter gebruiken.

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 standaardwaarden voor eigenschappen wilt instellen voor sommige aangepaste gebeurtenissen die u schrijft, kunt u deze instellen in een TelemetryClient-exemplaar. Ze zijn 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.

Gebruik voor JavaScript-web-clients JavaScript-telemetrie-initialisaties.

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

Telemetrie nemen, filteren en verwerken

U kunt code schrijven om uw telemetrie te verwerken voordat deze vanuit de SDK wordt verzonden. De verwerking omvat gegevens die worden verzonden vanuit de standaard telemetriemodules, zoals het verzamelen van HTTP-aanvragen en het verzamelen van afhankelijkheden.

Voeg eigenschappen toe aan telemetrie door te ITelemetryInitializer implementeren. U kunt bijvoorbeeld versienummers of waarden toevoegen die worden berekend op basis van andere eigenschappen.

Filteren kan telemetrie wijzigen of verwijderen voordat deze vanuit de SDK wordt verzonden door te ITelemetryProcessor implementeren. U kunt bepalen wat er wordt verzonden of verwijderd, maar u moet rekening houden met het effect op uw metrische gegevens. Afhankelijk van hoe u items kunt verwijderen, kunt u mogelijk niet meer navigeren tussen gerelateerde items.

Sampling is een verpakte oplossing om de hoeveelheid gegevens te verminderen die vanuit uw app naar de portal worden verzonden. Dit gebeurt zonder dat dit van invloed is op de weergegeven metrische gegevens. Dit gebeurt zonder dat dit van invloed is op de mogelijkheid om problemen te diagnosticeren door te navigeren tussen gerelateerde items, zoals uitzonderingen, aanvragen en paginaweergaven.

Meer informatie.

Telemetrie uitschakelen

Dynamisch stoppen en starten van het verzamelen en verzenden van telemetrie:

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Als u geselecteerde standaardverzamelaars(bijvoorbeeld prestatiemeters, HTTP-aanvragen of afhankelijkheden) wilt uitschakelen, verwijdert of uitcommenteert u de relevante regels in ApplicationInsights.config. U kunt dit bijvoorbeeld doen als u uw eigen TrackRequest-gegevens wilt verzenden.

Node.js

telemetry.config.disableAppInsights = true;

Als u geselecteerde standaardverzamelaars (bijvoorbeeld prestatiemeters, HTTP-aanvragen of afhankelijkheden) tijdens de initialisatie wilt uitschakelen, moet u configuratiemethoden aan uw SDK-initialisatiecode vastketenen:

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

Als u deze collectoren na de initialisatie wilt uitschakelen, gebruikt u het object Configuratie: applicationInsights.Configuration.setAutoCollectRequests(false)

Ontwikkelaarsmodus

Tijdens debuggen is het handig om uw telemetrie te versnellen via de pijplijn, zodat u onmiddellijk resultaten kunt zien. U krijgt ook aanvullende berichten die u helpen bij het traceren van problemen met de telemetrie. Schakel deze uit tijdens productie, omdat uw app hierdoor 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 in te schakelen via en in te stellen op 0, waardoor uw telemetrie wordt verzonden zodra setInternalLogging maxBatchSize 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

U kunt afzonderlijke Application Insights-resources maken en de sleutels ervan wijzigen, afhankelijk van de omgeving, om te voorkomen dat telemetrie uit ontwikkel-, test- en productieomgevingen wordt gemengd.

In plaats van de instrumentatiesleutel op te nemen uit het configuratiebestand, kunt u deze in uw code instellen. 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;

Op 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 context-eigenschap die waarden bevat die samen met alle telemetriegegevens worden verzonden. Ze worden doorgaans ingesteld door de standaard telemetriemodules, maar u kunt ze ook zelf instellen. Bijvoorbeeld:

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

Als u een van deze waarden zelf in stelt, kunt u overwegen om de relevante regel uitApplicationInsights.config, zodat uw waarden en de standaardwaarden niet in de war raken.

• Onderdeel: de app en de versie ervan.
• Apparaat: gegevens over het apparaat waarop de app wordt uitgevoerd. (In web-apps is dit de server of het clientapparaat van waar de telemetrie wordt verzonden.)
• InstrumentationKey: de application Insights resource in Azure waar de telemetrie wordt weergegeven. Dit wordt meestal opgehaald uit ApplicationInsights.config.
• Locatie: de geografische locatie van het apparaat.
• Bewerking: in web-apps de huidige HTTP-aanvraag. In andere app-typen kunt u dit instellen om gebeurtenissen te groepen.
  • Id: een gegenereerde waarde die verschillende gebeurtenissen correleert, zodat u gerelateerde items kunt vinden wanneer u een gebeurtenis inspecteert in Diagnostic Search.
  • Naam: een id, meestal de URL van de HTTP-aanvraag.
  • SyntheticSource: als deze niet null of leeg is, een tekenreeks die aangeeft dat de bron van de aanvraag is 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.
• 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.

Zie Over prijzen en quota voor Application Insights voor meer informatie.

Gebruik steekproeven om te voorkomen dat de limiet voor de gegevenssnelheid wordt bereikt.

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

Naslagdocumentatie

• ASP.NET naslag
• Naslaginformatie over Java
• Naslag voor JavaScript

SDK-code

• ASP.NET Core SDK
• ASP.NET
• Windows Serverpakketten
• Java SDK
• Node.js SDK
• JavaScript SDK

Vragen

• Welke uitzonderingen kunnen worden Track_()-aanroepen?

  Geen. U hoeft ze niet in try-catch-component te verpakken. Als de SDK problemen ondervindt, worden berichten in de foutopsporingsconsole-uitvoer en, als de berichten worden ontvangen, in Diagnostische zoekopdrachten in een logboek opgeslagen.

• 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 exporteren van Analytics naar Power BI en continue export.

Volgende stappen

• Gebeurtenissen en logboeken zoeken
• Problemen oplossen