API för Application Insights för anpassade händelser och mått

Infoga några rader med kod i ditt program för att ta reda på vad användarna gör med det eller för att diagnostisera problem. Du kan skicka telemetri från enhets- och skrivbordsappar, webbklienter och webbservrar. Använd Azure Application Insights core telemetry API för att skicka anpassade händelser och mått samt dina egna versioner av standardtelemetri. Det här API:et är samma API som standardprogrammet Insights datainsamlare använder.

API-sammanfattning

Kärn-API:et är enhetligt på alla plattformar, förutom några varianter som GetMetric (endast.NET).

Du kan koppla egenskaper och mått till de flesta av dessa telemetri-anrop.

Innan du börjar

Om du inte har någon referens för Application Insights SDK ännu:

• Lägg till Application Insights SDK i projektet:

  • ASP.NET projekt
  • ASP.NET Core projekt
  • Java-projekt
  • Node.js projekt
  • JavaScript på varje webbsida

• I din enhets- eller webbserverkod inkluderar du:

  C#:using Microsoft.ApplicationInsights;

  Visual Basic:Imports Microsoft.ApplicationInsights

  Java:import com.microsoft.applicationinsights.TelemetryClient;

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

Hämta en TelemetryClient-instans

Hämta en instans av TelemetryClient (förutom i JavaScript på webbsidor):

För ASP.NET Core-appar och icke-HTTP/Worker för .NET/.NET Core-appar rekommenderar vi att du hämtar en instans av från containern för beroendeinjektion enligt förklaringen i TelemetryClient respektive dokumentation.

Om du använder AzureFunctions v2+ eller Azure WebJobs v3+ följer du det här dokumentet.

C#

private TelemetryClient telemetry = new TelemetryClient();

Om du ser att den här metoden är föråldrad kan du läsa mer i microsoft/ApplicationInsights-dotnet#1152.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient är trådsäkert.

För ASP.NET- och Java-projekt hämtas inkommande HTTP-begäranden automatiskt. Du kanske vill skapa ytterligare instanser av TelemetryClient för andra moduler i din app. Du kan till exempel ha en TelemetryClient-instans i mellanprogramklassen för att rapportera affärslogikhändelser. Du kan ange egenskaper som UserId och DeviceId för att identifiera datorn. Den här informationen är kopplad till alla händelser som instansen skickar.

C#

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

Java

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

I Node.js projekt kan du använda för att skapa en ny instans, men detta rekommenderas endast för scenarier som kräver isolerad new applicationInsights.TelemetryClient(instrumentationKey?) konfiguration från defaultClient singletonen .

TrackEvent

I Application Insights är en anpassad händelse en datapunkt som du kan visa i Metrics Explorer som ett aggregerat antal och i Diagnostiksökning som enskilda förekomster. (Det är inte relaterat till MVC eller andra ramverk "händelser.")

Infoga TrackEvent anrop i koden för att räkna olika händelser. Hur ofta användarna väljer en viss funktion, hur ofta de uppnår specifika mål eller kanske hur ofta de gör särskilda typer av misstag.

I en spelapp kan du till exempel skicka en händelse när en användare vinner spelet:

JavaScript

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

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

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

Anpassade händelser i Analytics

Telemetrin finns i tabellen på customEvents fliken Application Insights Logs (Programloggar) eller Usage Experience (Användningsupplevelse). Händelser kan komma från trackEvent(..) eller klicka på Plugin-programmet För automatisk insamling av analys.

Om sampling används visar egenskapen itemCount ett värde större än 1. Till exempel innebär itemCount==10 att av 10 anrop till trackEvent() överför samplingsprocessen bara ett av dem. För att få rätt antal anpassade händelser bör du därför använda kod som customEvents | summarize sum(itemCount) .

GetMetric

Information om hur du effektivt använder GetMetric()-anropet för att samla in lokalt föraggregeringsmått för .NET- och .NET Core-program finns i GetMetric-dokumentationen.

TrackMetric

Program Insights kan diagrammått som inte är kopplade till vissa händelser. Du kan till exempel övervaka en kölängd med jämna mellanrum. Med mått är de enskilda måtten av mindre intresse än variationerna och trenderna, så statistiska diagram är användbara.

Du kan använda API:et för att Insights skicka mått till Application TrackMetric(..) Insights. Det finns två sätt att skicka ett mått:

• Enskilt värde. Varje gång du utför ett mått i ditt program skickar du motsvarande värde till Application Insights. Anta till exempel att du har ett mått som beskriver antalet objekt i en container. Under en viss tidsperiod lägger du först tre objekt i containern och sedan tar du bort två objekt. Därför skulle du anropa två TrackMetric gånger: först skicka värdet 3 och sedan värdet -2 . Program Insights lagrar båda värdena åt dig.

• Aggregation. När du arbetar med mått är varje enskild mätning sällan av intresse. En sammanfattning av vad som hände under en viss tidsperiod är i stället viktig. En sådan sammanfattning kallas aggregering. I exemplet ovan är den aggregerade måttsumman för den tidsperioden 1 och antalet måttvärden är 2 . När du använder aggregeringsmetod anropar du TrackMetric bara en gång per tidsperiod och skickar mängdvärdena. Det här är den rekommenderade metoden eftersom det avsevärt kan minska kostnaderna och prestandakostnaderna genom att skicka färre datapunkter till Application Insights, samtidigt som all relevant information samlas in.

Exempel

Enskilda värden

Så här skickar du ett enda måttvärde:

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

Anpassade mått i Analytics

Telemetrin är tillgänglig i tabellen customMetrics i Application Insights Analytics. Varje rad representerar ett anrop trackMetric(..) till i din app.

• valueSum – Det här är summan av måtten. Om du vill hämta medelvärdet dividera du med valueCount .
• valueCount – Antalet mått som aggregerades i det här trackMetric(..) anropet.

Sidvisningar

I en enhets- eller webbsideapp skickas telemetri för sidvisning som standard när varje skärm eller sida läses in. Men du kan ändra det om du vill spåra sidvisningar vid ytterligare eller olika tidpunkter. I en app som visar flikar eller blad kanske du till exempel vill spåra en sida när användaren öppnar ett nytt blad.

Användar- och sessionsdata skickas som egenskaper tillsammans med sidvisningar, så att användar- och sessionsdiagram blir levande när det finns telemetri för sidvisning.

Anpassade sidvisningar

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Om du har flera flikar på olika HTML-sidor kan du även ange webbadressen:

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

Sidvisningar för tidsinställning

Som standard mäts de tider som rapporteras som sidvisningens inläsningstid från när webbläsaren skickar begäran tills webbläsarens sidinläsningshändelse anropas.

I stället kan du antingen:

• Ange en explicit varaktighet i trackPageView-anropet: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds); .
• Använd tidsinställningssamtal för sidvisning startTrackPage och stopTrackPage .

JavaScript

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

...

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

Namnet som du använder som den första parametern associerar start- och stopp-anropen. Standardvärdet är det aktuella sidnamnet.

De resulterande sidinläsningstiderna som visas Metrics Explorer härleds från intervallet mellan start- och stopp-anropen. Det är upp till dig vilket intervall du faktiskt tar tid på.

Sidtelemetri i Analytics

I Analytics visar två tabeller data från webbläsaråtgärder:

• Tabellen pageViews innehåller data om URL:en och sidrubriken
• Tabellen browserTimings innehåller data om klientprestanda, till exempel hur lång tid det tar att bearbeta inkommande data

Så här tar det för webbläsaren att bearbeta olika sidor:

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

Så här identifierar du populära webbläsare:

pageViews
| summarize count() by client_Browser

Om du vill associera sidvyer med AJAX-anrop ansluter du till beroenden:

pageViews
| join (dependencies) on operation_Id 

TrackRequest

Server-SDK:n använder TrackRequest för att logga HTTP-begäranden.

Du kan också anropa den själv om du vill simulera begäranden i en kontext där du inte har webbtjänstmodulen igång.

Det rekommenderade sättet att skicka telemetri för förfrågningar är dock att begäran fungerar som en åtgärdskontext.

Åtgärdskontext

Du kan korrelera telemetriobjekt genom att koppla dem till åtgärdskontexten. Standardmodulen för spårning av förfrågningar gör detta för undantag och andra händelser som skickas när en HTTP-begäran bearbetas. I Sök och analys kandu enkelt hitta händelser som är associerade med begäran med hjälp av dess åtgärds-ID.

Se Telemetrikorrelation i Application Insights för mer information om korrelation.

När du spårar telemetri manuellt är det enklaste sättet att säkerställa telemetrikorrelation med hjälp av det här mönstret:

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.

Tillsammans med att ange en StartOperation åtgärdskontext skapar ett telemetriobjekt av den typ som du anger. Den skickar telemetriobjektet när du tar bort åtgärden, eller om du uttryckligen anropar StopOperation . Om du använder RequestTelemetry som telemetrityp anges varaktigheten till tidsintervallet mellan start och stopp.

Telemetriobjekt som rapporteras inom ett åtgärdsområde blir underordnade till sådana åtgärder. Åtgärdskontexterna kan kapslas.

I Sök används åtgärdskontexten för att skapa listan Relaterade objekt:

Mer information om spårning av anpassade åtgärder finns i Spåra anpassade åtgärder med Application Insights .NET SDK.

Begäranden i Analytics

I Application Insights Analyticsvisas begäranden i requests tabellen.

Om samplingen används visar egenskapen itemCount ett värde som är större än 1. Till exempel innebär itemCount==10 att av 10 anrop till trackRequest() överför samplingsprocessen bara ett av dem. Om du vill få ett korrekt antal begäranden och genomsnittlig varaktighet segmenterat efter begärandenamn använder du kod som:

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

TrackException

Skicka undantag till Program Insights:

• För att räknadem , som en indikation på frekvensen för ett problem.
• För att undersöka enskilda förekomster.

Rapporterna innehåller stackspårningarna.

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

SDK:erna fångar upp många undantag automatiskt, så du behöver inte alltid anropa TrackException explicit.

• ASP.NET: Skriv kod för att fånga upp undantag.
• Java EE: Undantag fångas automatiskt.
• JavaScript: Undantag fångas automatiskt. Om du vill inaktivera automatisk insamling lägger du till en rad i kodfragmentet som du infogar på webbsidorna:

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

Undantag i Analytics

I Application Insights Analyticsvisas undantag i exceptions tabellen.

Om sampling används visar egenskapen itemCount ett värde som är större än 1. Till exempel innebär itemCount==10 att av 10 anrop till trackException() överför samplingsprocessen bara ett av dem. Om du vill få ett korrekt antal undantag segmenterade efter typ av undantag använder du kod som:

exceptions
| summarize sum(itemCount) by type

Den mesta viktiga stackinformationen har redan extraherats i separata variabler, men du kan plocka isär strukturen details för att få mer. Eftersom den här strukturen är dynamisk bör du typge resultatet till den typ du förväntar dig. Ett exempel:

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

Om du vill associera undantag med deras relaterade begäranden använder du en koppling:

exceptions
| join (requests) on operation_Id

TrackTrace

Använd TrackTrace för att diagnostisera problem genom att skicka en "sökväg" till Application Insights. Du kan skicka segment med diagnostikdata och inspektera dem i Diagnostiksökning.

I .NET-loggkort använder du det här API:et för att skicka loggar från tredje part till portalen.

I Java samlar programmet Insights Java-agenten automatiskt in och skickar loggar till portalen.

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 på klient-/webbläsarsidan

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

Logga en diagnostikhändelse, till exempel att ange eller lämna en metod.

Du kan söka efter meddelandeinnehåll, men (till skillnad från egenskapsvärden) kan du inte filtrera på det.

Storleksgränsen för message är mycket högre än egenskapsgränsen. En fördel med TrackTrace är att du kan placera relativt långa data i meddelandet. Du kan till exempel koda POST-data där.

Dessutom kan du lägga till en allvarlighetsgrad i meddelandet. Och precis som med annan telemetri kan du lägga till egenskapsvärden som hjälper dig att filtrera eller söka efter olika uppsättningar av spårningar. Ett exempel:

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

I Sökkan du sedan enkelt filtrera bort alla meddelanden med en viss allvarlighetsgrad som är relaterade till en viss databas.

Spårningar i Analytics

I Application Insights Analyticsvisas anrop till TrackTrace i traces tabellen.

Om sampling används visar egenskapen itemCount ett värde större än 1. Till exempel innebär itemCount==10 att av 10 anrop till trackTrace() , överförde samplingsprocessen bara ett av dem. För att få rätt antal spårningssamtal bör du därför använda kod som traces | summarize sum(itemCount) .

TrackDependency

Använd TrackDependency-anropet för att spåra svarstider och lyckade anrop till ett externt kodstycke. Resultaten visas i beroendediagrammen i portalen. Kodfragmentet nedan måste läggas till överallt där ett beroendeanrop görs.

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

Kom ihåg att server-API:erna innehåller en beroendemodul som identifierar och spårar vissa beroendeanrop automatiskt, till exempel till databaser och REST-API:er. Du måste installera en agent på servern för att modulen ska fungera.

I Java kan många beroendeanrop spåras automatiskt med hjälp av Application Insights Java-agenten.

Du använder det här anropet om du vill spåra anrop som inte fångas upp av den automatiserade spårningen.

Om du vill inaktivera standardmodulen för beroendespårning i C# redigerarApplicationInsights.config och tar bort referensen till DependencyCollector.DependencyTrackingTelemetryModule . För Java, se förhindra specifik automatiskt insamlad telemetri.

Beroenden i Analytics

I Application Insights Analyticsvisas trackDependency-anrop i dependencies tabellen.

Om sampling används visar egenskapen itemCount ett värde större än 1. Till exempel innebär itemCount==10 att av 10 anrop till trackDependency() överförde samplingsprocessen bara ett av dem. Om du vill få rätt antal beroenden segmenterade efter målkomponent använder du kod som:

dependencies
| summarize sum(itemCount) by target

Om du vill associera beroenden med deras relaterade begäranden använder du en koppling:

dependencies
| join (requests) on operation_Id

Rensa data

Vanligtvis skickar SDK data med fasta intervall (vanligtvis 30 sekunder) eller när bufferten är full (vanligtvis 500 objekt). I vissa fall kan du dock vilja tömma bufferten, till exempel om du använder SDK i ett program som stängs av.

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

Funktionen är asynkron för serverns telemetrikanal.

Vi rekommenderar att flush()-metoden används i programmets avstängningsaktivitet.

Autentiserade användare

I en webbapp identifieras användare (som standard) av cookies. En användare kan räknas mer än en gång om de kommer åt din app från en annan dator eller webbläsare, eller om de tar bort cookies.

Om användarna loggar in på din app kan du få ett mer korrekt antal genom att ange det autentiserade användar-ID:t i webbläsarkoden:

JavaScript

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

I ett ASP.NET MVC-webbprogram, till exempel:

Razor

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

Du behöver inte använda användarens faktiska inloggningsnamn. Det behöver bara vara ett ID som är unikt för den användaren. Det får inte innehålla blanksteg eller något av tecknen ,;=| .

Användar-ID:t anges också i en sessions-cookie och skickas till servern. Om server-SDK har installerats skickas det autentiserade användar-ID:t som en del av kontextegenskaperna för både klient- och servertelemetri. Du kan sedan filtrera och söka efter den.

Om din app grupperar användare till konton kan du även skicka en identifierare för kontot (med samma teckenbegränsningar).

appInsights.setAuthenticatedUserContext(validatedId, accountId);

I Metrics Explorerkan du skapa ett diagram som räknar användare, autentiserade och användarkonton.

Du kan också Söka efter klientdatapunkter med specifika användarnamn och konton.

Filtrera, söka och segmentera data med hjälp av egenskaper

Du kan koppla egenskaper och mått till dina händelser (och även till mått, sidvisningar, undantag och andra telemetridata).

Egenskaper är strängvärden som du kan använda för att filtrera telemetrin i användningsrapporterna. Om din app till exempel innehåller flera spel kan du koppla namnet på spelet till varje händelse så att du kan se vilka spel som är mer populära.

Stränglängden har en gräns på 8192. (Om du vill skicka stora databitar använder du meddelandeparametern i TrackTrace.)

Mått är numeriska värden som kan visas grafiskt. Du kanske till exempel vill se om det sker en gradvis ökning av poängen som din nana uppnår. Graferna kan segmenteras av de egenskaper som skickas med händelsen, så att du kan få separata eller staplade grafer för olika spel.

För att måttvärden ska visas korrekt bör de vara större än eller lika med 0.

Det finns vissa begränsningar för antalet egenskaper, egenskapsvärden och mått som du kan använda.

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

Alternativt sätt att ange egenskaper och mått

Om det är mer praktiskt kan du samla in parametrarna för en händelse i ett separat objekt:

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

Anpassade mått och egenskaper i Analytics

I Analyticsvisas anpassade mått och egenskaper i attributen customMeasurements och för varje customDimensions telemetripost.

Om du till exempel har lagt till en egenskap med namnet "spel" i din begärandetelemetri räknar den här frågan antalet förekomster av olika värden för "spel" och visar medelvärdet av det anpassade måttet "poäng":

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

Observera att:

• När du extraherar ett värde från customDimensions eller customMeasurements JSON har det dynamisk typ, så du måste typge tostring det eller todouble .
• Om du vill ta hänsyn till risken för samplingbör du använda , sum(itemCount) inte count() .

Tidshändelser

Ibland vill du ta reda på hur lång tid det tar att utföra en åtgärd. Du kanske till exempel vill veta hur lång tid det tar för användarna att överväga val i ett spel. Du kan använda måttparametern för detta.

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

Standardegenskaper för anpassad telemetri

Om du vill ange standardegenskapsvärden för några av de anpassade händelser som du skriver kan du ange dem i en TelemetryClient-instans. De är kopplade till varje telemetriobjekt som skickas från klienten.

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

Enskilda telemetrianrop kan åsidosätta standardvärdena i deras egenskapsordlistor.

För JavaScript-webbklienter använder du JavaScript-telemetriinitierare.

Om du vill lägga till egenskaper i all telemetri, inklusive data från standardsamlingsmoduler, implementerar du ITelemetryInitializer.

Sampling, filtrering och bearbetning av telemetri

Du kan skriva kod för att bearbeta telemetrin innan den skickas från SDK:n. Bearbetningen omfattar data som skickas från standardmodulerna för telemetri, till exempel insamling av HTTP-begäranden och beroendeinsamling.

Lägg till egenskaper i telemetrin genom att implementera ITelemetryInitializer . Du kan till exempel lägga till versionsnummer eller värden som beräknas från andra egenskaper.

Filtrering kan ändra eller ta bort telemetri innan den skickas från SDK:n genom att implementera ITelemetryProcessor . Du styr vad som skickas eller tas bort, men du måste ta hänsyn till effekten på dina mått. Beroende på hur du tar bort objekt kan du förlora möjligheten att navigera mellan relaterade objekt.

Sampling är en paketerad lösning för att minska mängden data som skickas från din app till portalen. Det gör det utan att de mått som visas påverkas. Och det gör det utan att det påverkar din möjlighet att diagnostisera problem genom att navigera mellan relaterade objekt, till exempel undantag, begäranden och sidvisningar.

Läs mer.

Inaktivera telemetri

Stoppa och starta insamling och överföring av telemetri dynamiskt:

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Om du vill inaktivera valda standardinsamlare, till exempel prestandaräknare, HTTP-begäranden eller beroenden, tar du bort eller kommenterar bort relevanta rader i ApplicationInsights.config. Du kan till exempel göra detta om du vill skicka dina egna TrackRequest-data.

Node.js

telemetry.config.disableAppInsights = true;

Inaktivera valda standardinsamlare– till exempel prestandaräknare, HTTP-begäranden eller beroenden – vid initieringstid, kedjekonfigurationsmetoder till SDK-initieringskoden:

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

Om du vill inaktivera dessa insamlare efter initieringen använder du objektet Konfiguration: applicationInsights.Configuration.setAutoCollectRequests(false)

Utvecklarläge

Under felsökningen är det bra att få telemetrin att gå igenom pipelinen så att du kan se resultatet direkt. Du får också ytterligare meddelanden som hjälper dig att spåra eventuella problem med telemetrin. Stäng av den i produktion eftersom det kan göra appen långsammare.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Till Node.js kan du aktivera utvecklarläge genom att aktivera intern loggning via och ange till 0, vilket gör att din telemetri skickas så snart setInternalLogging maxBatchSize den samlas in.

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

Ange instrumenteringsnyckeln för vald anpassad telemetri

C#

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

Dynamisk instrumenteringsnyckel

För att undvika att blanda telemetri från utvecklings-, test- och produktionsmiljöer kan du skapa separata program Insights-resurser och ändra deras nycklar, beroende på miljön.

I stället för att hämta instrumenteringsnyckeln från konfigurationsfilen kan du ange den i koden. Ange nyckeln i en initieringsmetod, till exempel global.aspx.cs i en ASP.NET tjänst:

C#

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

JavaScript

appInsights.config.instrumentationKey = myKey;

På webbsidor kanske du vill ställa in den från webbserverns tillstånd, i stället för att koda den bokstavligen i skriptet. Till exempel på en webbsida som genereras i en ASP.NET app:

JavaScript i 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 har en kontextegenskap som innehåller värden som skickas tillsammans med alla telemetridata. De anges vanligtvis av standardmodulerna för telemetri, men du kan också ange dem själv. Ett exempel:

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

Om du själv anger något av dessa värden bör du överväga att ta bort den relevanta raden frånApplicationInsights.config, så att dina värden och standardvärdena inte blir förvirrade.

• Komponent: Appen och dess version.
• Enhet: Data om enheten där appen körs. (I webbappar är detta den server eller klientenhet som telemetrin skickas från.)
• InstrumentationKey: Programmet Insights resurs i Azure där telemetrin visas. Den hämtas vanligtvis från ApplicationInsights.config.
• Plats: Enhetens geografiska plats.
• Åtgärd: Den aktuella HTTP-begäran i webbappar. I andra apptyper kan du ställa in detta för att gruppera händelser.
  • ID: Ett genererat värde som korrelerar olika händelser, så att du kan hitta relaterade objekt när du inspekterar en händelse i diagnostiksökningen.
  • Namn: En identifierare, vanligtvis URL:en för HTTP-begäran.
  • SyntheticSource: Om den inte är null eller tom, en sträng som anger att källan för begäran har identifierats som en robot eller ett webbtest. Som standard undantas den från beräkningar i Metrics Explorer.
• Session: Användarens session. ID:t anges till ett genererat värde som ändras när användaren inte har varit aktiv på ett tag.
• Användare: Användarinformation.

Gränser

Det finns vissa begränsningar för antalet mått och händelser per program, det vill säga per Instrumentation-nyckel. Gränserna beror på vilken prisplan du väljer.

Mer information finns i Om priser och kvoter i Application Insights.

Använd sampling för att undvika att nå datahastighetsgränsen.

Information om hur länge data sparas finns i Datalagring och sekretess.

Referensdokument

• ASP.NET referens
• Java-referens
• JavaScript-referens

SDK-kod

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

Frågor

• Vilka undantag kan Track_()-anrop?

  Inga. Du behöver inte omsluta dem i try-catch-satser. Om SDK stöter på problem loggas meddelanden i felsökningskonsolens utdata och – om meddelandena skickas via diagnostisk sökning.

• Finns det REST API att hämta data från portalen?

  Ja, API:et för dataåtkomst. Andra sätt att extrahera data är export från Analytics till Power BI och kontinuerlig export.

Nästa steg

• Söka efter händelser och loggar
• Felsökning