Rozhraní API služby Application Insights pro vlastní události a metriky

Do své aplikace vložte pár řádků kódu, abyste zjistili, co uživatelé s ním pracují, nebo aby vám pomohla diagnostikovat problémy. Telemetrii můžete odesílat ze zařízení a desktopových aplikací, webových klientů a webových serverů. použijte rozhraní API telemetrie Azure Application Insights core k posílání vlastních událostí a metrik a vašich vlastních verzí standardní telemetrie. toto rozhraní api je stejné rozhraní api, které používá standardní Application Insights sběrače dat.

Souhrn rozhraní API

Základní rozhraní API je na všech platformách stejné, kromě několika variant, jako je GetMetric (jenom .NET).

K většině těchto volání telemetrie můžete připojit vlastnosti a metriky .

Než začnete

pokud ještě nemáte odkaz na Application Insights SDK, postupujte takto:

• přidejte sadu Application Insights SDK do projektu:

  • ASP.NET projekt
  • ASP.NET Core projekt
  • Projekt Java
  • Node.js projekt
  • JavaScript na každé webové stránce

• Do kódu zařízení nebo webového serveru zadejte:

  Jazyk C#:using Microsoft.ApplicationInsights;

  Visual Basic:Imports Microsoft.ApplicationInsights

  Java:import com.microsoft.applicationinsights.TelemetryClient;

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

Získat instanci TelemetryClient

Získat instanci TelemetryClient (kromě v jazyce JavaScript na webových stránkách):

pro aplikace ASP.NET Core a Non HTTP/worker pro .net/.net Core se doporučuje získat instanci TelemetryClient z kontejneru injektáže vkládání závislostí, jak je vysvětleno v příslušné dokumentaci.

Pokud používáte AzureFunctions v2 + nebo Azure WebJobs v3 +, postupujte podle tohoto dokumentu.

C#

private TelemetryClient telemetry = new TelemetryClient();

Pro každého, kdo vidí tuto metodu, jsou zastaralé zprávy, další podrobnosti najdete v 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 je bezpečný pro přístup z více vláken.

pro ASP.NET a Java jsou automaticky zachyceny příchozí požadavky HTTP. Možná budete chtít vytvořit další instance TelemetryClient pro jiný modul aplikace. Například můžete mít jednu instanci TelemetryClient ve vaší třídě middleware pro hlášení událostí obchodní logiky. Můžete nastavit vlastnosti, jako je například UserId a DeviceId, a identifikovat počítač. Tyto informace jsou připojeny ke všem událostem, které instance odesílá.

C#

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

Java

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

V Node.js projekty můžete použít new applicationInsights.TelemetryClient(instrumentationKey?) k vytvoření nové instance, ale toto nastavení se doporučuje jenom pro scénáře, které vyžadují izolovanou konfiguraci z typu Singleton defaultClient .

TrackEvent

v Application Insights vlastní událost je datový bod, který lze zobrazit v Průzkumník metrik jako agregovaný počet a v diagnostickém vyhledávání jako jednotlivé výskyty. (Nesouvisí s událostmi MVC nebo jinými rozhraními.)

Vložením TrackEvent volání do kódu můžete spočítat různé události. Jak často uživatelé vyberou konkrétní funkci, jak často dosahují konkrétního cíle, nebo jak často provádějí konkrétní typy chyb.

Například v herní aplikaci můžete odeslat událost pokaždé, když uživatel hry vyhrává:

JavaScript

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

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

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

Vlastní události v analýzách

telemetrii je k dispozici v customEvents tabulce na kartě protokoly Application Insights nebo v prostředí používání. Události můžou pocházet z trackEvent(..) nebo kliknout na analýza modul plug-in automatické kolekce.

Pokud je vzorkování v provozu, vlastnost vlastnost ItemCount zobrazí hodnotu větší než 1. Například vlastnost ItemCount = = 10 znamená, že u 10 volání trackEvent () proces vzorkování přenáší pouze jeden z nich. Chcete-li získat správný počet vlastních událostí, měli byste proto použít kód jako customEvents | summarize sum(itemCount) .

GetMetric

Chcete-li se dozvědět, jak efektivně použít volání getmetric () k zachycení místně předem agregovaných metrik pro aplikace .NET a .NET Core, přejděte do dokumentace ke službě getmetric .

TrackMetric

Application Insights mohou metriky grafů, které nejsou připojeny k určitým událostem. Můžete například monitorovat délku fronty v pravidelných intervalech. Díky metrikám jsou jednotlivá měření méně zajímavá než kolísání a trendy, takže statistické grafy jsou užitečné.

aby bylo možné odesílat metriky do Application Insights, můžete použít TrackMetric(..) rozhraní API. Existují dva způsoby, jak odeslat metriku:

• Jedna hodnota. pokaždé, když ve své aplikaci provedete měření, odešlete odpovídající hodnotu Application Insights. Předpokládejme například, že máte metriku popisující počet položek v kontejneru. Během konkrétního časového období nejprve do kontejneru vložíte tři položky a pak odeberete dvě položky. Proto byste volali TrackMetric dvakrát: nejprve předání hodnoty 3 a hodnoty -2 . Application Insights ukládá vaše jménem obě hodnoty.

• Agregovat. Při práci s metrikami je každé jedno měření málo důležité. Místo toho je důležité mít přehled o tom, co se stalo během konkrétního časového období. Tento souhrn se nazývá agregace. Ve výše uvedeném příkladu je agregovaná celková metrika pro toto časové období 1 a počet hodnot metrik 2 . Při použití agregačního přístupu, vyvolejte pouze TrackMetric jednou za časové období a odešlete agregované hodnoty. to je doporučený postup, protože může významně snížit náklady a režii na výkon tím, že posílá méně datových bodů do Application Insights a přitom stále shromažďuje všechny relevantní informace.

Příklady

Jednotlivé hodnoty

Odeslání jedné hodnoty metriky:

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

Vlastní metriky v analýzách

telemetrii je k dispozici v customMetrics tabulce v Application Insights Analytics. Každý řádek představuje volání trackMetric(..) ve vaší aplikaci.

• valueSum – Toto je součet měření. Chcete-li získat střední hodnotu, rozdělte valueCount .
• valueCount – Počet měření, které byly agregovány do tohoto trackMetric(..) volání.

Zobrazení stránek

V aplikaci pro zařízení nebo webovou stránku se telemetrie zobrazení stránky ve výchozím nastavení posílá při načtení každé obrazovky nebo stránky. Ale můžete změnit, aby se zobrazení stránek sledovalo v dalších nebo různých časech. Například v aplikaci, která zobrazuje karty nebo okna, může být vhodné sledovat stránku vždy, když uživatel otevře nové okno.

Data uživatelů a relací se odesílají jako vlastnosti spolu se zobrazeními stránek, takže grafy uživatelů a relací budou aktivní, když se zobrazí telemetrie zobrazení stránky.

Vlastní zobrazení stránky

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Pokud máte v různých stránkách HTML několik karet, můžete zadat i adresu URL:

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

Zobrazení časování stránky

Ve výchozím nastavení jsou časy hlášené jako Doba načítání zobrazení stránky měřeny od okamžiku, kdy prohlížeč požadavek odešle, dokud není volána událost načtení stránky prohlížeče.

Místo toho můžete použít tyto kroky:

• Nastavte explicitní dobu trvání ve volání trackPageView : appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds); .
• Použijte zobrazení na stránce s časováním volání startTrackPage a stopTrackPage .

JavaScript

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

...

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

Název, který použijete jako první parametr, přidruží volání Start a stop. Výchozí hodnota je název aktuální stránky.

Výsledná trvání načtení stránky zobrazená v Průzkumník metrik jsou odvozena z intervalu mezi voláními spuštění a zastavení. To je až na vás, jaký interval ve skutečnosti vydáte.

Telemetrie stránky v analýzách

V analytických dvou tabulkách se zobrazují data z operací prohlížeče:

• pageViewsTabulka obsahuje data o adrese URL a názvu stránky.
• browserTimingsTabulka obsahuje data o výkonu klienta, například čas potřebný ke zpracování příchozích dat.

Pokud chcete zjistit, jak dlouho bude prohlížeč zpracovávat různé stránky, postupujte takto:

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

Pro zjištění oblíbených různých prohlížečů:

pageViews
| summarize count() by client_Browser

Chcete-li přidružit zobrazení stránky voláním AJAX, připojte se k závislostem:

pageViews
| join (dependencies) on operation_Id 

TrackRequest

Sada SDK serveru používá TrackRequest k protokolování požadavků HTTP.

Můžete ji také zavolat sami, pokud chcete simulovat žádosti v kontextu, ve kterém nemáte spuštěný modul webové služby.

Doporučený způsob odeslání telemetrie požadavků je však, že požadavek funguje jako kontext operace.

Kontext operace

Můžete sladit položky telemetrie dohromady jejich přidružením k kontextu operace. Standardní modul pro sledování požadavků provádí tyto výjimky a další události, které jsou odeslány během zpracování požadavku HTTP. V části vyhledávání a Analýzamůžete snadno najít jakékoli události přidružené k žádosti pomocí jejího ID operace.

další informace o korelaci najdete v tématu korelace telemetrie v Application Insights .

Při ručním sledování telemetrie je nejjednodušší způsob, jak zajistit korelace telemetrie pomocí tohoto modelu:

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.

Spolu s nastavením kontextu operace StartOperation vytvoří položku telemetrie typu, který zadáte. Odesílá položku telemetrie při uvolnění operace, nebo pokud explicitně voláte StopOperation . Pokud použijete RequestTelemetry jako typ telemetrie, jeho doba trvání je nastavená na časový interval mezi začátkem a zastavením.

Položky telemetrie hlášené v rámci oboru operace se stanou "podřízenými" takové operace. Kontexty operace můžou být vnořené.

V části Hledat se k vytvoření seznamu souvisejících položek používá kontext operace:

další informace o sledování vlastních operací najdete v tématu sledování vlastních operací pomocí Application Insights .net SDK .

Požadavky v analýzách

v Application Insights Analyticsse žádosti zobrazují v requests tabulce.

Pokud je vzorkování v provozu, vlastnost vlastnost ItemCount zobrazí hodnotu větší než 1. Například vlastnost ItemCount = = 10 znamená, že u 10 volání trackRequest () proces vzorkování přenáší pouze jeden z nich. Chcete-li získat správný počet požadavků a průměrnou dobu, segmentované podle názvů požadavků, použijte následující kód:

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

TrackException

odeslat výjimky do Application Insights:

• Pokud je chcete spočítat, jako indikaci četnosti problému.
• K prohlédnutí jednotlivých výskytů.

Sestavy zahrnují trasování zásobníku.

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

Sady SDK zachycují mnoho výjimek automaticky, takže nemusíte vždy volat TrackException explicitně.

• ASP.NET: napište kód pro zachycení výjimek.
• Java EE: výjimky se zachycují automaticky.
• JavaScript: výjimky jsou zachyceny automaticky. Pokud chcete zakázat automatické shromažďování, přidejte řádek do fragmentu kódu, který vložíte do webových stránek:

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

Výjimky v analýzách

v Application Insights Analyticsse výjimky zobrazují v exceptions tabulce.

Pokud je vzorkování v provozu, itemCount vlastnost zobrazuje hodnotu větší než 1. Například vlastnost ItemCount = = 10 znamená, že u 10 volání trackException () proces vzorkování přenáší pouze jeden z nich. Chcete-li získat správný počet výjimek segmenticky podle typu výjimky, použijte kód jako:

exceptions
| summarize sum(itemCount) by type

Většina důležitých informací o zásobníku se už extrahuje do samostatných proměnných, ale pokud chcete získat další informace, můžete si ji stáhnout ze své details struktury. Vzhledem k tomu, že je tato struktura dynamická, je vhodné přetypovat výsledek na očekávaný typ. Příklad:

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

K přidružení výjimek ke svým souvisejícím žádostem použijte spojení:

exceptions
| join (requests) on operation_Id

TrackTrace

pomocí TrackTrace můžete diagnostikovat problémy odesláním "popisu cesty" do Application Insights. Můžete odeslat bloky diagnostických dat a zkontrolovat je v diagnostickém vyhledávání.

V adaptérech protokolů .NET použijte toto rozhraní API k posílání protokolů třetích stran na portál.

v jazyce java agent Application Insights Java automaticky shromažďuje a odesílá protokoly na portál.

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 na straně klienta nebo prohlížeče

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

Protokoluje diagnostickou událost, jako je například zadání nebo ukončení metody.

Obsah zprávy můžete hledat, ale (na rozdíl od hodnot vlastností) ho nemůžete filtrovat.

Omezení velikosti message u je mnohem vyšší než limit vlastností. Výhodou trackTrace je, že do zprávy můžete umístit relativně dlouhá data. Můžete tam například kódovat data POST.

Kromě toho můžete ke zprávě přidat úroveň závažnosti. Stejně jako u jiných telemetrických dat můžete přidat hodnoty vlastností, které vám pomůžou filtrovat nebo hledat různé sady trasování. Příklad:

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

V částiHledat pak můžete snadno vyfiltrovat všechny zprávy určité úrovně závažnosti, které se vztahují ke konkrétní databázi.

Trasování v analýzách

V části Application Přehledy Analyticsse v tabulce zobrazí volání TrackTrace. traces

Pokud je vzorkování v provozu, vlastnost itemCount zobrazí hodnotu větší než 1. Například itemCount==10 znamená, že z 10 volání metody se při vzorkování trackTrace() přeložil pouze jeden z nich. Pokud chcete získat správný počet volání trasování, měli byste použít například kód traces | summarize sum(itemCount) .

TrackDependency

Volání TrackDependency slouží ke sledování dob odezvy a úspěšnosti volání do externí části kódu. Výsledky se zobrazí v grafech závislostí na portálu. Níže uvedený fragment kódu je potřeba přidat všude, kde je provedeno volání závislosti.

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

Mějte na paměti, že serverové sdk obsahují modul závislostí, který automaticky zjišťuje a sleduje určitá volání závislostí – například do databází a rozhraní REST API. Aby modul fungoval, musíte na server nainstalovat agenta.

V Javě lze mnoho volání závislostí automaticky sledovat pomocí agenta Application Přehledy Java.

Toto volání použijete, pokud chcete sledovat volání, která automatizované sledování nezachytí.

Pokud chcete standardní modul pro sledování závislostí v jazyce C# vypnout, ApplicationInsights.config a odstraňte odkaz na DependencyCollector.DependencyTrackingTelemetryModule . Informace o Javě najdete v tématu potlačení konkrétní automaticky shromažďované telemetrie.

Závislosti v analýzách

V části Application Přehledy Analyticsse v tabulce zobrazí volání trackDependency. dependencies

Pokud je vzorkování v provozu, vlastnost itemCount zobrazí hodnotu větší než 1. Například itemCount==10 znamená, že z 10 volání metody trackDependency() proces vzorkování přeložil pouze jeden z nich. Pokud chcete získat správný počet závislostí segmentovaných podle cílové komponenty, použijte například následující kód:

dependencies
| summarize sum(itemCount) by target

Pokud chcete přidružit závislosti k souvisejícím požadavkům, použijte spojení:

dependencies
| join (requests) on operation_Id

Vyprazdnění dat

Za normálních okolností sada SDK odesílá data v pevných intervalech (obvykle 30 sekund) nebo vždy, když je vyrovnávací paměť plná (obvykle 500 položek). V některých případech však můžete chtít vyrovnávací paměť vyprázdnit – například pokud používáte sadu SDK v aplikaci, která se vypne.

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

Funkce je asynchronní pro kanál telemetrie serveru.

V ideálním případě by se v aktivitě vypnutí aplikace měla použít metoda flush().

Skupina Authenticated Users

Ve webové aplikaci jsou uživatelé (ve výchozím nastavení) identifikováni pomocí souborů cookie. Pokud uživatel přistupí k aplikaci z jiného počítače nebo prohlížeče nebo když soubory cookie odstraní, může se spočítat vícekrát.

Pokud se uživatelé přihlásí k vaší aplikaci, můžete získat přesnější počet nastavením ověřeného ID uživatele v kódu prohlížeče:

JavaScript

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

V ASP.NET webové aplikaci MVC, například:

Razor

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

Skutečné přihlašovací jméno uživatele není nutné používat. Musí to být jenom ID, které je pro tohoto uživatele jedinečné. Nesmí obsahovat mezery ani žádné znaky ,;=| .

ID uživatele se také nastaví v souboru cookie relace a odesílá se na server. Pokud je nainstalovaná sada SDK serveru, je ověřené ID uživatele odesláno jako součást vlastností kontextu telemetrie klienta i serveru. Pak ho můžete filtrovat a vyhledávat.

Pokud vaše aplikace seskupí uživatele do účtů, můžete také předat identifikátor účtu (se stejnými omezeními znaků).

appInsights.setAuthenticatedUserContext(validatedId, accountId);

V Průzkumník metrikmůžete vytvořit graf, který počítá účty Users, Authenticated a User .

Můžete také vyhledat klientské datové body s konkrétními uživatelskými jmény a účty.

Filtrování, vyhledávání a segmentace dat pomocí vlastností

K událostem (a také k metrikám, zobrazením stránek, výjimám a dalším telemetrickým datům) můžete připojit vlastnosti a měření.

Vlastnosti jsou řetězcové hodnoty, které můžete použít k filtrování telemetrie v sestavách využití. Pokud například vaše aplikace nabízí několik her, můžete ke každé události připojit název hry, abyste viděli, které hry jsou oblíbenější.

Pro délku řetězce platí limit 8192. (Pokud chcete odesílat velké bloky dat, použijte parametr zprávy TrackTrace.)

Metriky jsou číselné hodnoty, které lze graficky prezentovat. Můžete například chtít zobrazit, jestli se skóre, které vaši hráči dosáhnou, postupně zvyšuje. Grafy je možné segmentovat podle vlastností, které se odesílaly s událostí, abyste mohli získat samostatné nebo skládané grafy pro různé hry.

Aby se správně zobrazují hodnoty metrik, měly by být větší než nebo rovno 0.

Existuje několik omezení počtu vlastností, hodnot vlastností a metrik, které můžete použít.

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

Alternativní způsob nastavení vlastností a metrik

Pokud je to pohodlnější, můžete shromáždit parametry události v samostatném objektu:

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

Vlastní měření a vlastnosti v Analytics

V analyticese vlastní metriky a vlastnosti zobrazují v atributech a každého customMeasurements záznamu customDimensions telemetrie.

Pokud jste například do telemetrie požadavku přidali vlastnost s názvem "game", tento dotaz spočítá výskyty různých hodnot "game" a zobrazí průměr vlastní metriky "score":

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

Všimněte si, že:

• Při extrahování hodnoty z json customDimensions nebo customMeasurements má dynamický typ, a proto ho musíte přetypovat tostring nebo todouble .
• Pokud chcete vzít v úvahu možnost vzorkování, měli byste použít sum(itemCount) , nikoli count() .

Události časování

Někdy chcete zobrazit graf, jak dlouho trvá provedení akce. Můžete například chtít vědět, jak dlouho uživatelům trvá zvážení voleb ve hře. K tomu můžete použít parametr měření.

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

Výchozí vlastnosti pro vlastní telemetrii

Pokud chcete nastavit výchozí hodnoty vlastností pro některé vlastní události, které píšete, můžete je nastavit v instanci TelemetryClient. Jsou připojeny ke každé položce telemetrie odeslané z tohoto klienta.

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

Jednotlivá telemetrická volání mohou přepsat výchozí hodnoty ve svých slovníkech vlastností.

Pro webové klienty JavaScriptu použijte inicializátory telemetrie JavaScriptu.

Pokud chcete přidat vlastnosti ke všem telemetrii, včetně dat ze standardních modulů shromažďování, implementujte ITelemetryInitializer.

Vzorkování, filtrování a zpracování telemetrie

Můžete napsat kód pro zpracování telemetrie před odesláním ze sady SDK. Zpracování zahrnuje data odesílaná ze standardních modulů telemetrie, jako je shromažďování požadavků HTTP a shromažďování závislostí.

Implementací přidejte vlastnosti do ITelemetryInitializer telemetrie. Můžete například přidat čísla verzí nebo hodnoty, které se počítají z jiných vlastností.

Filtrování může upravit nebo zahodit telemetrii před odesláním ze sady SDK implementací ITelemetryProcessor . Řídíte, co se posílá nebo zahodí, ale musíte zohlednit vliv na metriky. V závislosti na způsobu zahození položek můžete ztratit možnost přecházet mezi souvisejícími položkami.

Vzorkování je zabalené řešení, které snižuje objem dat odesílaných z aplikace na portál. Dělá to, aniž by to ovlivnilo zobrazené metriky. A to bez ovlivnění schopnosti diagnostikovat problémy navigací mezi souvisejícími položkami, jako jsou výjimky, požadavky a zobrazení stránek.

Přečtěte si další informace.

Zakázání telemetrie

Dynamické zastavení a spuštění shromažďování a přenosu telemetrie:

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Pokud chcete zakázat vybrané standardní kolektory(například čítače výkonu, požadavky HTTP nebo závislosti), odstraňte nebo zakomentujte příslušné řádky v ApplicationInsights.config. Můžete to udělat například v případě, že chcete odeslat vlastní data TrackRequest.

Node.js

telemetry.config.disableAppInsights = true;

Pokud chcete vybrané standardní kolektory(například čítače výkonu, požadavky HTTP nebo závislosti) zakázat při inicializaci, zřetězte metody konfigurace s inicializačním kódem sady SDK:

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

Pokud chcete tyto kolektory po inicializaci zakázat, použijte objekt Configuration: applicationInsights.Configuration.setAutoCollectRequests(false)

Vývojářský režim

Během ladění je užitečné zrychlit telemetrii prostřednictvím kanálu, abyste okamžitě viděli výsledky. Získáte také další zprávy, které vám pomůžou sledovat případné problémy s telemetrií. Vypněte ho v produkčním prostředí, protože to může vaši aplikaci zpomalit.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Například Node.js povolit vývojářský režim tím, že povolíte interní protokolování přes a nastavíte na 0, což způsobí odeslání telemetrie ihned po setInternalLogging maxBatchSize jejich shromažďování.

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

Nastavení instrumentačního klíče pro vybranou vlastní telemetrii

C#

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

Dynamický instrumentační klíč

Pokud se chcete vyhnout kombinaci telemetrie z vývojového, testovacího a produkčního prostředí, můžete vytvořit samostatné prostředky Application Přehledy a změnit jejich klíče v závislosti na prostředí.

Místo získání instrumentačního klíče z konfiguračního souboru ho můžete nastavit v kódu. Nastavte klíč v inicializační metodě, například global.aspx.cs v ASP.NET službě:

C#

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

JavaScript

appInsights.config.instrumentationKey = myKey;

Na webových stránkách ho můžete chtít nastavit ze stavu webového serveru, místo abyste ho kódovat do skriptu doslovně. Například na webové stránce vygenerované v ASP.NET aplikace:

JavaScript v Razoru

<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 má vlastnost Context, která obsahuje hodnoty odeslané spolu se všemi telemetrickými daty. Obvykle se nastavují standardními moduly telemetrie, ale můžete si je také nastavit sami. Příklad:

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

Pokud nastavíte jakoukoli z těchto hodnot sami, zvažte odebrání příslušného řádku z ApplicationInsights.config, aby se vaše hodnoty a standardní hodnoty nezaměňují.

• Součást: Aplikace a její verze.
• Zařízení: Data o zařízení, ve kterém je aplikace spuštěná. (Ve webových aplikacích je to server nebo klientské zařízení, ze které se telemetrie odesílá.)
• InstrumentationKey: Služba Application Přehledy v Azure, kde se telemetrie zobrazuje. Obvykle se vyzvedne z ApplicationInsights.config.
• Umístění: Zeměpisné umístění zařízení.
• Operace: Ve webových aplikacích aktuální požadavek HTTP. V jiných typech aplikací můžete nastavit seskupení událostí.
  • ID: Vygenerovaná hodnota, která koreluje různé události, takže při kontrole jakékoli události v diagnostickém vyhledávání můžete najít související položky.
  • Název: Identifikátor, obvykle adresa URL požadavku HTTP.
  • SyntheticSource: Pokud není null nebo prázdný, řetězec, který označuje, že zdroj požadavku byl identifikován jako robot nebo webový test. Ve výchozím nastavení je vyloučen z výpočtů v Průzkumník metrik.
• Relace: Relace uživatele. ID je nastavené na vygenerovanou hodnotu, která se změní, když uživatel nebyl po chvíli aktivní.
• Uživatel: Informace o uživateli.

Omezení

K dispozici jsou určitá omezení počtu metrik a událostí na aplikaci, tj. na klíč instrumentace. Omezení závisí na zvoleném cenovém plánu.

Další informace najdete v tématu Ceny a kvóty ve službě Application Insights.

Pokud se chcete vyhnout limitu přenosové rychlosti dat, použijte vzorkování.

Informace o tom, jak dlouho se data uchovávají, najdete v tématu Uchovávání dat a ochrana osobních údajů.

Referenční dokumenty

• ASP.NET referenční informace
• Reference k Javě
• Referenční informace k JavaScriptu

Kód sady SDK

• Sada ASP.NET Core SDK
• ASP.NET
• Windows Serverové balíčky
• Java SDK
• Node.js SDK
• JavaScript SDK

Dotazy

• Jaké výjimky mohou Track_() vyvolat volání?

  Žádné Není nutné je zabalit do klauzulí try-catch. Pokud sada SDK narazí na problémy, zachytá zprávy ve výstupu konzoly ladění a pokud se zprávy prochytá, v diagnostickém vyhledávání.

• Existuje REST API získat data z portálu?

  Ano, rozhraní API pro přístup k datům. Mezi další způsoby extrakce dat patří export z Analytics do Power BI a průběžný export.

Další kroky

• Prohledávání událostí a protokolů
• Řešení potíží