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

  • Artikel

Infoga några rader kod i programmet 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 Application Insights-kärntelemetri-API:et för att skicka anpassade händelser och mått och dina egna versioner av standardtelemetri. Det här API:et är samma API som standarddatainsamlaren i Application Insights använder.

Kommentar

Stödet för inmatning av instrumentationsnycklar upphör den 31 mars 2025. Inmatningen av instrumenteringsnyckeln fortsätter att fungera, men vi kommer inte längre att tillhandahålla uppdateringar eller stöd för funktionen. Övergå till anslutningssträng för att dra nytta av nya funktioner.

API-sammanfattning

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

Metod Används för
TrackPageView Sidor, skärmar, fönster eller formulär.
TrackEvent Användaråtgärder och andra händelser. Används för att spåra användarbeteende eller för att övervaka prestanda.
GetMetric Noll- och flerdimensionella mått, centralt konfigurerad aggregering, endast C#.
TrackMetric Prestandamått som kölängder som inte är relaterade till specifika händelser.
TrackException Loggningsfel för diagnos. Spåra var de inträffar i förhållande till andra händelser och granska stackspårningar.
TrackRequest Logga frekvensen och varaktigheten för serverbegäranden för prestandaanalys.
TrackTrace Loggmeddelanden för resursdiagnostik. Du kan också samla in loggar från tredje part.
TrackDependency Logga varaktigheten och frekvensen för anrop till externa komponenter som appen är beroende av.

Du kan koppla egenskaper och mått till de flesta av dessa telemetrianrop.

Innan du börjar

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

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 hämtar du en instans av TelemetryClient från containern för beroendeinmatning enligt beskrivningen i respektive dokumentation.

Om du använder Azure Functions v2+ eller Azure WebJobs v3+ läser du Övervaka Azure Functions.

C#

private TelemetryClient telemetry = new TelemetryClient();

Om du ser ett meddelande om 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äker.

För ASP.NET- och Java-projekt registreras inkommande HTTP-begäranden automatiskt. Du kanske vill skapa fler instanser av TelemetryClient för andra moduler i din app. Du kan till exempel ha en TelemetryClient instans i mellanprogramsklassen 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 new applicationInsights.TelemetryClient(instrumentationKey?) för att skapa en ny instans. Vi rekommenderar den här metoden endast för scenarier som kräver isolerad konfiguration från singleton defaultClient.

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 ramverkshändelser.)

Infoga TrackEvent anrop i koden för att räkna olika händelser. Du kanske till exempel vill spåra hur ofta användare väljer en viss funktion. Eller så kanske du vill veta hur ofta de uppnår vissa mål eller gör specifika typer av misstag.

I en spelapp kan du till exempel skicka ett evenemang 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 Log Analytics

Telemetrin är tillgänglig i customEvents tabellen på fliken Application Insights-loggar eller användningsupplevelsen. Händelser kan komma från trackEvent(..) eller plugin-programmet Klicka på Analys för automatisk insamling.

Om samplingen är i drift visar egenskapen itemCount ett värde som är större än 1. Innebär till exempel itemCount==10 att av 10 anrop till trackEvent()överförde samplingsprocessen bara en av dem. Om du vill få ett korrekt antal anpassade händelser använder du kod som customEvents | summarize sum(itemCount).

Kommentar

itemCount har ett minimivärde på ett. själva posten representerar en post.

GetMetric

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

TrackMetric

Kommentar

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric är inte den bästa metoden för att skicka mått. Mått bör alltid föraggregeras under en tidsperiod innan de skickas. Använd en av överlagringarna GetMetric(..) för att hämta ett måttobjekt för åtkomst till SDK-föraggregeringsfunktioner.

Om du implementerar din egen föraggregeringslogik kan du använda TrackMetric() metoden för att skicka de resulterande aggregeringarna. Om ditt program kräver att ett separat telemetriobjekt skickas vid varje tillfälle utan aggregering över tid, har du förmodligen ett användningsfall för händelsetelemetri. Se TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights kan kartlägga må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ätningarna av mindre intresse än variationerna och trenderna, och därför är statistiska diagram användbara.

Om du vill skicka mått till Application Insights kan du använda API:et TrackMetric(..) . Det finns två sätt att skicka ett mått:

  • Enskilt värde. Varje gång du utför en mätning 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 placerar du först tre objekt i containern och tar sedan bort två objekt. Därför skulle du ringa TrackMetric två gånger. Först skickar du värdet 3 och skickar sedan värdet -2. Application Insights lagrar båda värdena åt dig.

  • Sammansättning. När du arbetar med mått är varje enskild mätning sällan av intresse. I stället är en sammanfattning av vad som hände under en viss tidsperiod viktig. En sådan sammanfattning kallas aggregering.

    I föregående exempel är 1 den aggregerade måttsumman för den tidsperioden och antalet måttvärden är 2. När du använder aggregeringsmetoden anropar TrackMetric du bara en gång per tidsperiod och skickar aggregeringsvärdena. Vi rekommenderar den här metoden eftersom den avsevärt kan minska kostnaderna och prestandakostnaderna genom att skicka färre datapunkter till Application Insights, samtidigt som all relevant information samlas in.

Exempel med ett enda värde

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.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

Anpassade mått i Log Analytics

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

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

Kommentar

valueCount har ett minsta värde på ett. själva posten representerar en post.

Sidvisningar

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

Användar- och sessionsdata skickas som egenskaper tillsammans med sidvyer, så användar- och sessionsdiagram kommer till liv när det finns telemetri för sidvisning.

Anpassade sidvyer

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 också ange URL:en:

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

Sidvyer för tidsinställningar

Som standard mäts de tider som rapporteras som inläsningstid för sidvisning 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 tidsanrop startTrackPage för sidvisning 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 stoppanropen. Det är som standard det aktuella sidnamnet.

De resulterande sidinläsningsvaraktigheterna som visas i Metrics Explorer härleds från intervallet mellan start- och stoppanropen. Det är upp till dig vilket intervall du faktiskt tid.

Sidtelemetri i Log Analytics

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

  • pageViews: Innehåller data om URL:en och sidrubriken.
  • browserTimings: Innehåller data om klientprestanda som den tid det tar att bearbeta inkommande data.

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

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

Så här upptäcker du populariteten för olika webbläsare:

pageViews
| summarize count() by client_Browser

Koppla sidvisningar till AJAX-anrop genom att ansluta till beroenden:

pageViews
| join (dependencies) on operation_Id

TrackRequest

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

Du kan också anropa det 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 begäran är när begäran fungerar som en åtgärdskontext.

Åtgärdskontext

Du kan korrelera telemetriobjekt genom att associera dem med åtgärdskontexten. Standardmodulen för spårning av begäranden gör detta för undantag och andra händelser som skickas medan en HTTP-begäran bearbetas. I Sök och Analys kan du enkelt hitta alla händelser som är associerade med begäran med hjälp av dess åtgärds-ID.

Mer information om korrelation finns i Telemetrikorrelation i Application Insights.

När du spårar telemetri manuellt är det enklaste sättet att säkerställa telemetrikorrelation genom att använda 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 åtgärdskontext StartOperation 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 är dess varaktighet inställd på det tidsintervall mellan start och stopp.

Telemetriobjekt som rapporteras inom en åtgärdsomfång blir underordnade en sådan åtgärd. Åtgärdskontexter kan kapslas.

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

Skärmbild som visar 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 Log Analytics

I Application Insights Analytics visas begäranden i requests tabellen.

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

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

TrackException

Skicka undantag till Application Insights:

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:

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

Undantag i Log Analytics

I Application Insights Analytics visas undantag i exceptions tabellen.

Om samplingen är i drift visar egenskapen itemCount ett värde som är större än 1. Innebär till exempel itemCount==10 att av 10 anrop till trackException()överförde samplingsprocessen bara en 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

Det mesta av den viktiga stackinformationen extraheras redan i separata variabler, men du kan dra isär details strukturen för att få mer. Eftersom den här strukturen är dynamisk bör du omvandla resultatet till den typ du förväntar dig. Till 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 "breadcrumb trail" till Application Insights. Du kan skicka delar av 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 Application 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 som att ange eller lämna en metod.

Parameter Description
message Diagnostikdata. Kan vara mycket längre än ett namn.
properties Karta över sträng till sträng. Mer data används för att filtrera undantag i portalen. Standardvärdet är tomt.
severityLevel Värden som stöds: SeverityLevel.ts.

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

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

Du kan också lägga till en allvarlighetsgrad i meddelandet. Och precis som andra telemetrier kan du lägga till egenskapsvärden som hjälper dig att filtrera eller söka efter olika uppsättningar spårningar. Till 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ök kan du sedan enkelt filtrera bort alla meddelanden på en viss allvarlighetsnivå som är relaterade till en viss databas.

Spårningar i Log Analytics

I Application Insights Analytics anropas för att TrackTrace visas i traces tabellen.

Om samplingen är i drift visar egenskapen itemCount ett värde som är större än 1. Innebär till exempel itemCount==10 att av 10 anrop till trackTrace()överförde samplingsprocessen bara en av dem. Om du vill få ett korrekt antal spårningsanrop använder du kod som traces | summarize sum(itemCount).

TrackDependency

Använd anropet TrackDependency för att spåra svarstiderna och framgångsfrekvensen för anrop till en extern kod. Resultaten visas i beroendediagrammen i portalen. Följande kodfragment måste läggas till varhelst ett beroendeanrop görs.

Kommentar

För .NET och .NET Core kan du alternativt använda TelemetryClient.StartOperation metoden (tillägg) som fyller de DependencyTelemetry egenskaper som behövs för korrelation och vissa andra egenskaper som starttid och varaktighet, så du behöver inte skapa en anpassad timer som med följande exempel. Mer information finns i avsnittet om spårning av utgående beroenden i Spåra anpassade åtgärder med Application Insights .NET SDK.

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-SDK: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 den automatiserade spårningen inte fångar upp.

Om du vill inaktivera standardmodulen för beroendespårning i C# redigerar du ApplicationInsights.config och tar bort referensen till DependencyCollector.DependencyTrackingTelemetryModule. För Java, se Utelämna specifik autokollected telemetri.

Beroenden i Log Analytics

I Application Insights AnalyticstrackDependency visas anrop i dependencies tabellen.

Om samplingen är i drift visar egenskapen itemCount ett värde som är större än 1. Innebär till exempel itemCount==10 att av 10 anrop till trackDependency()överförde samplingsprocessen bara en av dem. Om du vill få ett korrekt 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

Normalt skickar SDK:t data med fasta intervall, vanligtvis 30 sekunder, eller när bufferten är full, vilket vanligtvis är 500 objekt. I vissa fall kanske du vill tömma bufferten. Ett exempel är om du använder SDK:t i ett program som stängs av.

.NET

När du använder Flush()rekommenderar vi det här mönstret:

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

När du använder FlushAsync()rekommenderar vi det här mönstret:

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

Vi rekommenderar att du alltid rensar som en del av programavstängningen för att garantera att telemetri inte går förlorad.

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.

Kommentar

Java- och JavaScript-SDK:erna rensas automatiskt vid programavstängning.

Autentiserade användare

I en webbapp identifieras användare som standard med 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 exakt 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 webb-MVC-program, till exempel:

Razor

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

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

Användar-ID:t anges också i en sessionscookie och skickas till servern. Om server-SDK:t är installerat 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 på den.

Om appen grupperar användare till konton kan du också skicka en identifierare för kontot. Samma teckenbegränsningar gäller.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

I Metrics Explorer kan 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.

Kommentar

Egenskapen EnableAuthenticationTrackingJavaScript i klassen ApplicationInsightsServiceOptions i .NET Core SDK förenklar JavaScript-konfigurationen som behövs för att mata in användarnamnet som autentiserings-ID för varje spårning som skickas av Application Insights JavaScript SDK.

När den här egenskapen är inställd truepå skrivs användarnamnet från användaren i ASP.NET Core ut tillsammans med telemetri på klientsidan. Därför behövs det inte längre att lägga till appInsights.setAuthenticatedUserContext manuellt eftersom det redan har injicerats av SDK:t för ASP.NET Core. Auth-ID:t skickas också till servern där SDK:t i .NET Core identifierar det och använder det för all telemetri på serversidan, enligt beskrivningen i JavaScript API-referensen.

För JavaScript-program som inte fungerar på samma sätt som ASP.NET Core MVC, till exempel SPA-webbappar, skulle du fortfarande behöva lägga appInsights.setAuthenticatedUserContext till manuellt.

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

Du kan koppla egenskaper och mått till dina händelser, 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 tillhandahå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.

Det finns en gräns på 8 192 för stränglängden. Om du vill skicka stora datasegment använder du meddelandeparametern TrackTraceför .

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 dina spelare uppnår. Graferna kan segmenteras efter de egenskaper som skickas med händelsen så att du kan få separata eller staplade grafer för olika spel.

Måttvärdena ska vara större än eller lika med 0 för att visas korrekt.

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

Kommentar

Kontrollera att du inte loggar personligt identifierbar information i egenskaper.

Alternativt sätt att ange egenskaper och mått

Om det är enklare 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);

Varning

Återanvänd inte samma telemetriobjektinstans (event i det här exemplet) för att anropa Track*() flera gånger. Den här metoden kan leda till att telemetri skickas med felaktig konfiguration.

Anpassade mått och egenskaper i Log Analytics

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

Om du till exempel lägger till en egenskap med namnet "game" i din telemetri för begäran räknar den här frågan förekomsterna av olika värden för "spel" och visar medelvärdet av det anpassade måttet "score":

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 en dynamisk typ, så du måste omvandla det tostring eller todouble.
  • Om du vill ta hänsyn till möjligheten till sampling ska du inte count()använda sum(itemCount) .

Tidsinställningar

Ibland vill du visa 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. Använd måttparametern för att hämta den här informationen.

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 anger du 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 sina egenskapsordlistor.

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

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

Exempel, filter och processtelemetri

Se Filtrera och förbearbeta telemetri i Application Insights SDK.

Inaktivera telemetri

För att dynamiskt stoppa och starta insamling och överföring av telemetri:

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 ut relevanta rader i ApplicationInsights.config. Ett exempel är om du vill skicka egna TrackRequest data.

Node.js

telemetry.config.disableAppInsights = true;

Om du vill inaktivera valda standardinsamlare, till exempel prestandaräknare, HTTP-begäranden eller beroenden, vid initieringstillfället, kedjar du konfigurationsmetoder till din SDK-initieringskod.

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

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

Utvecklarläge

Under felsökningen är det bra att få telemetrin snabbare via pipelinen så att du kan se resultat direkt. Du får även andra meddelanden som hjälper dig att spåra eventuella problem med telemetrin. Stäng av den i produktion eftersom den kan göra din app långsammare.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

För Node.js kan du aktivera utvecklarläge genom att aktivera intern loggning via setInternalLogging och inställning maxBatchSize till 0, vilket gör att telemetrin skickas så snart den samlas in.

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

Ange instrumentationsnyckeln 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 Application Insights-resurser och ändra deras nycklar beroende på miljön.

I stället för att hämta instrumentationsnyckeln 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 ange den från webbserverns tillstånd i stället för att bokstavligen koda den 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);
    }

TelemetriContext

TelemetryClient har en kontextegenskap som innehåller värden som skickas tillsammans med alla telemetridata. De anges normalt av standardtelemetrimodulerna, men du kan också ange dem själv. Till exempel:

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

Om du anger något av dessa värden själv kan du överväga att ta bort relevant rad från ApplicationInsights.config så att dina värden och standardvärden inte blir förvirrade.

  • Komponent: Appen och dess version.
  • Enhet: Data om enheten där appen körs. I webbappar är det den server eller klientenhet som telemetrin skickas från.
  • InstrumentationKey: Application Insights-resursen i Azure där telemetrin visas. Den hämtas vanligtvis från ApplicationInsights.config.
  • Plats: Enhetens geografiska plats.
  • Åtgärd: I webbappar, den aktuella HTTP-begäran. I andra apptyper kan du ange det här värdet för att gruppera händelser tillsammans.
    • 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ökning.
    • Namn: En identifierare, vanligtvis URL:en för HTTP-begäran.
    • SyntheticSource: Om den inte är null eller tom har en sträng som anger att källan till 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 är inställt på 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 gränser för antalet mått och händelser per program, dvs. per instrumentationsnyckel. Gränserna beror på vilken prisplan du väljer.

Resurs Standardgräns Maximigräns Kommentar
Totala data per dag 100 GB Kontakta supporten. Du kan ange ett tak för att minska data. Om du behöver mer data kan du öka gränsen i portalen, upp till 1 000 GB. För kapaciteter som är större än 1 000 GB skickar du e-post till AIDataCap@microsoft.com.
Begränsning 32 000 händelser/sekund Kontakta supporten. Gränser är mätt under en minut.
Datakvarhållningsloggar 30 till 730 dagar 730 dagar Den här resursen är för Loggar.
Datakvarhållningsmått 90 dagar 90 dagar Den här resursen är för Metrics Explorer.
Kvarhållning av detaljerade resultat för flerstegstest för tillgänglighet 90 dagar 90 dagar Den här resursen innehåller detaljerade resultat för varje steg.
Maximal storlek på telemetriobjekt 64 KB 64 KB
Maximalt antal telemetriobjekt per batch 64,000 64,000
Namnlängd för egenskaper och mätvärden 150 150 Se typscheman.
Stränglängd för egenskapsvärde 8,192 8,192 Se typscheman.
Längd för spårnings- och undantagsmeddelande 32,768 32,768 Se typscheman.
Tillgänglighetstester räknas per Application Insights-resurs 100 100
Datakvarhållning för profiler och ögonblicksbilder Två veckor Kontakta supporten. Maximal kvarhållningsgräns är sex månader.
Profileringsdata skickas per dag Ingen begränsning Ingen gräns.
Ögonblicksbildsdata som skickas per dag 30 ögonblicksbilder per dag per övervakad app Ingen gräns. Antalet ögonblicksbilder som samlas in per program kan ändras via konfigurationen.

Mer information om priser och kvoter finns i Application Insights-fakturering.

Om du vill undvika att nå datahastighetsgränsen använder du sampling.

Information om hur länge data sparas finns i Datakvarhållning och sekretess.

Referensdokument

SDK-kod

Vanliga frågor och svar

Det här avsnittet innehåller svar på vanliga frågor.

Varför saknar jag telemetridata?

Båda TelemetryChannels förlorar buffrad telemetri om den inte töms innan ett program stängs av.

För att undvika dataförlust rensar du TelemetryClient när ett program stängs av.

Mer information finns i Rensa data.

Vilka undantag kan Track_() anrop utlösa?

Inga. Du behöver inte omsluta dem i try-catch-satser. Om SDK:et stöter på problem loggar det meddelanden i felsökningskonsolens utdata och, om meddelandena kommer igenom, i Diagnostiksökning.

Finns det ett REST-API för att hämta data från portalen?

Ja, API:et för dataåtkomst. Andra sätt att extrahera data är Power BI om du har migrerat till en arbetsytebaserad resurs eller kontinuerlig export om du fortfarande använder en klassisk resurs.

Varför ignoreras mina anrop till anpassade händelser och mått-API:er?

Application Insights SDK är inte kompatibelt med autoinstrumentation. Om autoinstrumentation är aktiverat ignoreras anrop till Track() och andra anpassade händelser och mått-API:er.

Inaktivera autoinstrumentation i Azure-portalen på fliken Application Insights på sidan App Service eller ange ApplicationInsightsAgent_EXTENSION_VERSION till disabled.

Varför är antalet i sök- och måttdiagram olika?

Sampling minskar antalet telemetriobjekt (till exempel begäranden och anpassade händelser) som skickas från din app till portalen. I Sök ser du antalet mottagna objekt. I måttdiagram som visar antalet händelser ser du antalet ursprungliga händelser som har inträffat.

Varje objekt som överförs har en itemCount egenskap som visar hur många ursprungliga händelser som objektet representerar. Om du vill observera sampling i drift kan du köra den här frågan i Log Analytics:

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

Hur ställer jag in en avisering för en händelse?

Azure-aviseringar gäller endast mått. Skapa ett anpassat mått som överskrider ett värdetröskelvärde när händelsen inträffar. Ange sedan en avisering för måttet. Du får ett meddelande när måttet överskrider tröskelvärdet i båda riktningarna. Du får inget meddelande förrän den första korsningen, oavsett om det ursprungliga värdet är högt eller lågt. Det finns alltid en svarstid på några minuter.

Nästa steg