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

Vložte do aplikace několik řádků kódu, abyste zjistili, co s ním uživatelé dělají, nebo abyste mohli diagnostikovat problémy. Můžete odesílat telemetrii ze zařízení a desktopových aplikací, webových klientů a webových serverů. Pomocí základního rozhraní API telemetrie Application Insights můžete odesílat vlastní události a metriky a vlastní verze standardní telemetrie. Toto rozhraní API je stejné rozhraní API, které používají standardní kolektory dat Application Insights.

Poznámka:

Podpora příjmu dat založeného na instrumentačním klíči skončí 31. března 2025. Příjem klíčů instrumentace bude dál fungovat, ale už nebudeme poskytovat aktualizace ani podporu pro tuto funkci. Přechod na připojovací řetězec, abyste mohli využívat nové funkce.

Souhrn rozhraní API

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

metoda	Použití
TrackPageView	Stránky, obrazovky, podokna nebo formuláře
TrackEvent	Akce uživatelů a další události Používá se ke sledování chování uživatelů nebo ke sledování výkonu.
GetMetric	Nulové a multidimenzionální metriky, centrálně nakonfigurované agregace, pouze C#.
TrackMetric	Měření výkonu, jako jsou délky front, nesouvisely s konkrétními událostmi.
TrackException	Protokolování výjimek pro diagnostiku Trasování, kde se vyskytují ve vztahu k jiným událostem, a zkoumání trasování zásobníku
TrackRequest	Protokolování frekvence a doby trvání požadavků serveru pro analýzu výkonu
TrackTrace	Zprávy protokolu diagnostiky prostředků Můžete také zaznamenávat protokoly třetích stran.
TrackDependency	Protokolování doby trvání a frekvence volání externích komponent, na které vaše aplikace závisí.

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 sadu Application Insights SDK:

• Přidejte do projektu sadu Application Insights SDK:

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

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

  C#: using Microsoft.ApplicationInsights;

  Visual Basic: Imports Microsoft.ApplicationInsights

  Java: import com.microsoft.applicationinsights.TelemetryClient;

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

Získání instance TelemetryClient

Získání instance TelemetryClient (s výjimkou JavaScriptu na webových stránkách):

V případě aplikací ASP.NET Core a jiných než HTTP/Worker pro aplikace .NET/.NET Core získejte instanci TelemetryClient z kontejneru injektáže závislostí, jak je vysvětleno v příslušné dokumentaci.

Pokud používáte Azure Functions v2 nebo Azure WebJobs v3+, přečtěte si téma Monitorování Azure Functions.

C#

private TelemetryClient telemetry = new TelemetryClient();

Pokud se zobrazí zpráva s informací, že tato metoda je zastaralá, další informace najdete v tématu 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é vlákno.

U projektů ASP.NET a Java se příchozí požadavky HTTP zachytávají automaticky. Možná budete chtít vytvořit další instance pro další moduly TelemetryClient vaší aplikace. Můžete mít například v middlewarové třídě jednu TelemetryClient instanci pro hlášení událostí obchodní logiky. Můžete nastavit vlastnosti, například UserId a DeviceId 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 projektech můžete vytvořit new applicationInsights.TelemetryClient(instrumentationKey?) novou instanci. Tento přístup doporučujeme pouze pro scénáře, které vyžadují izolovanou konfiguraci od singletonu defaultClient.

TrackEvent

Ve službě Application Insights je vlastní událost datovým bodem, který můžete v Průzkumníku metrik zobrazit jako agregovaný počet a v diagnostickém vyhledávání jako jednotlivé výskyty. (Nesouvisí s MVC ani s jinými "událostmi".)

Vložte TrackEvent do kódu volání, která počítají různé události. Můžete například chtít sledovat, jak často si uživatelé vyberou konkrétní funkci. Nebo můžete chtít vědět, jak často dosahují určitých cílů nebo dělají určité typy chyb.

Například v aplikaci hry odešlete událost pokaždé, když uživatel vyhraje hru:

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 Log Analytics

Telemetrie je dostupná v customEvents tabulce na kartě Protokoly Application Insights nebo v prostředí využití. Události můžou pocházet z trackEvent(..) modulu plug-in automatické kolekce Click Analytics.

Pokud je vzorkování v provozu, itemCount vlastnost zobrazuje hodnotu větší než 1. Například znamená, itemCount==10 že 10 volání trackEvent(), proces vzorkování přenášel pouze jeden z nich. Pokud chcete získat správný počet vlastních událostí, použijte kód, například customEvents | summarize sum(itemCount).

Poznámka:

itemCount má minimální hodnotu jedné; samotný záznam představuje položku.

GetMetric

Informace o efektivním využití GetMetric() volání k zachycení místně předem agregovaných metrik pro aplikace .NET a .NET Core najdete v tématu Vlastní kolekce metrik v .NET a .NET Core.

TrackMetric

Poznámka:

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric není upřednostňovanou metodou odesílání metrik. Metriky by se měly před odesláním vždy předem agregovat napříč časovým obdobím. Pomocí jednoho z GetMetric(..) přetížení získejte objekt metriky pro přístup k možnostem předběžné agregace sady SDK.

Pokud implementujete vlastní logiku předběžné agregace, můžete použít metodu TrackMetric() k odeslání výsledných agregací. Pokud vaše aplikace vyžaduje odesílání samostatné položky telemetrie při každé příležitosti bez agregace v čase, pravděpodobně máte případ použití pro telemetrii událostí. Viz třída TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

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

K odesílání metrik do Application Insights můžete použít TrackMetric(..) rozhraní API. Metriku můžete odeslat dvěma způsoby:

• Jedna hodnota. Pokaždé, když v aplikaci provedete měření, odešlete odpovídající hodnotu do Application Insights.

  Předpokládejme například, že máte metriku, která popisuje počet položek v kontejneru. Během určitého časového období nejprve vložíte do kontejneru tři položky a pak odeberete dvě položky. Proto byste volali TrackMetric dvakrát. Nejprve byste předali hodnotu 3 a pak předali hodnotu -2. Application Insights ukládá obě hodnoty za vás.

• Agregace. Při práci s metrikami je každé měření zřídka zajímavé. Místo toho je důležité shrnutí toho, co se stalo během určitého časového období. Takový souhrn se nazývá agregace.

  V předchozím příkladu je 1 agregační součet metrik pro dané časové období a počet hodnot metriky .2 Při použití přístupu k agregaci vyvoláte TrackMetric pouze jednou za časové období a odešlete agregované hodnoty. Tento přístup doporučujeme, protože může výrazně snížit náklady a výkon tím, že do Application Insights odesílá méně datových bodů, zatímco stále shromažďuje všechny relevantní informace.

Příklady s jednou hodnotou

Odeslání jedné hodnoty metriky:

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

Vlastní metriky v Log Analytics

Telemetrie je dostupná v tabulce v customMetrics Analýzách Application Insights. Každý řádek představuje volání trackMetric(..) v aplikaci.

• valueSum: Součet měření. Chcete-li získat střední hodnotu, vydělte hodnotou valueCount.
• valueCount: Počet měření agregovaných do tohoto trackMetric(..) volání.

Poznámka:

valueCount má minimální hodnotu jedné; samotný záznam představuje položku.

Zobrazení stránek

V zařízení nebo webové aplikaci se při načtení každé obrazovky nebo stránky ve výchozím nastavení odesílá telemetrie zobrazení stránky. Výchozí nastavení ale můžete změnit tak, aby sledovala zobrazení stránek ve více nebo různých časech. Například v aplikaci, která zobrazuje karty nebo podokna, můžete chtít sledovat stránku pokaždé, když uživatel otevře nové podokno.

Data uživatelů a relací se odesílají jako vlastnosti spolu se zobrazeními stránek, takže grafy uživatelů a relací při zobrazení stránky přijdou naživu.

Vlastní zobrazení stránek

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

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

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

Zobrazení stránek časování

Ve výchozím nastavení se časy hlášené jako doba načítání zobrazení stránky měří od doby, kdy prohlížeč odešle požadavek, dokud se nevolá událost načtení stránky prohlížeče.

Místo toho můžete:

• Nastavte explicitní dobu trvání volání trackPageView : appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
• Použijte volání startTrackPage časování zobrazení stránky 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í spuštění a zastavení. Výchozí hodnota je název aktuální stránky.

Výsledné doby načítání stránky zobrazené v Průzkumníku metrik jsou odvozeny z intervalu mezi spuštěním a zastavením volání. Je na vás, jaký interval skutečně časujete.

Telemetrie stránek v Log Analytics

V Log Analytics zobrazují dvě tabulky data z operací prohlížeče:

• pageViews: Obsahuje data o adrese URL a názvu stránky.
• browserTimings: Obsahuje data o výkonu klienta, jako je doba potřebná ke zpracování příchozích dat.

Jak dlouho prohlížeč trvá zpracování různých stránek:

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

Pokud chcete zjistit popularitu různých prohlížečů:

pageViews
| summarize count() by client_Browser

Pokud chcete přidružit zobrazení stránek k voláním AJAX, připojte se k závislostem:

pageViews
| join (dependencies) on operation_Id

TrackRequest

Serverová sada SDK používá TrackRequest k protokolování požadavků HTTP.

Můžete ho také volat sami, pokud chcete simulovat požadavky v kontextu, kde nemáte spuštěný modul webové služby.

Doporučeným způsobem odesílání telemetrie požadavků je místo, kde požadavek funguje jako kontext operace.

Kontext operace

Položky telemetrie můžete vzájemně korelovat tím, že je přidružíte k kontextu operace. Standardní modul pro sledování požadavků to dělá u výjimek a dalších událostí, které se odesílají při zpracování požadavku HTTP. Ve službě Search a Analytics můžete snadno najít všechny události přidružené k požadavku pomocí ID operace.

Další informace o korelaci najdete v tématu Korelace telemetrie v Application Insights.

Pokud telemetrii sledujete ručně, nejjednodušší způsob, jak zajistit korelaci telemetrie pomocí tohoto vzoru:

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 StartOperation operace vytvoří položku telemetrie zadaného typu. Odesílá položku telemetrie, když odstraníte operaci nebo pokud explicitně zavoláte StopOperation. Pokud jako typ telemetrie použijete RequestTelemetry , jeho doba trvání se nastaví na časový interval mezi spuštěním a zastavením.

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

Při hledání se kontext operace používá k vytvoření seznamu Souvisejících položek .

Další informace o sledování vlastníchoperacích

Požadavky v Log Analytics

V Application Insights Analytics se požadavky zobrazí v requests tabulce.

Pokud je vzorkování v provozu, itemCount vlastnost zobrazuje hodnotu větší než 1. Například znamená, itemCount==10 že 10 volání trackRequest(), proces vzorkování přenášel pouze jeden z nich. Pokud chcete získat správný počet požadavků a průměrnou dobu trvání segmentovanou podle názvů požadavků, použijte kód, například:

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

TrackException

Odesílání výjimek do Application Insights:

• Pokud je chcete spočítat, jako indikátor četnosti problému.
• Chcete-li prozkoumat jednotlivé výskyty.

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 automaticky zachytí mnoho výjimek, takže nemusíte vždy volat TrackException explicitně:

• ASP.NET: Napište kód, který zachytí výjimky.
• Java EE: Výjimky se zachytí automaticky.
• JavaScript: Výjimky se zachytí automaticky. Pokud chcete zakázat automatické shromažďování, přidejte řádek do skriptu zavaděče sady JavaScript (Web) SDK, který vložíte do webových stránek:

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

Výjimky v Log Analytics

V Application Insights Analytics se výjimky zobrazují v exceptions tabulce.

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

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ší možnosti, můžete strukturu oddělit details . Vzhledem k tomu, že je tato struktura dynamická, měli byste výsledek přetypovat na očekávaný typ. Příklad:

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

Pokud chcete přidružit výjimky k souvisejícím požadavkům, použijte připojení:

exceptions
| join (requests) on operation_Id

TrackTrace

Slouží TrackTrace k diagnostice problémů odesláním "cesty s popisem cesty" do Application Insights. Můžete odesílat bloky diagnostických dat a kontrolovat je v diagnostickém vyhledávání.

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

V Javě se agent Java Application Insights automaticky zahlcuje 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
})

Zaznamená diagnostickou událost, jako je zadání nebo opuštění metody.

Parametr	Popis
message	Diagnostická data. Může být mnohem delší než název.
properties	Mapování řetězce na řetězec Další data se používají k filtrování výjimek na portálu. Výchozí hodnota je prázdná.
severityLevel	Podporované hodnoty: SeverityLevel.ts.

Obsah zprávy můžete prohledávat, ale na rozdíl od hodnot vlastností na něm nemůžete filtrovat.

Limit message velikosti je mnohem vyšší než limit vlastností. Výhodou TrackTrace je, že do zprávy můžete vložit relativně dlouhá data. Můžete tam například zakódovat data POST.

Ke zprávě můžete také přidat úroveň závažnosti. A stejně jako jiné telemetrie můžete přidat hodnoty vlastností, které vám pomůžou filtrovat nebo vyhledávat 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);

Ve službě Search pak můžete snadno vyfiltrovat všechny zprávy konkrétní úrovně závažnosti, které souvisejí s konkrétní databází.

Trasování v Log Analytics

V Application Insights Analytics se volání, která se TrackTrace mají zobrazit v traces tabulce.

Pokud je vzorkování v provozu, itemCount vlastnost zobrazuje hodnotu větší než 1. Například znamená, itemCount==10 že 10 volání trackTrace(), proces vzorkování přenášel pouze jeden z nich. Pokud chcete získat správný počet volání trasování, použijte kód, například traces | summarize sum(itemCount).

TrackDependency

TrackDependency Volání slouží ke sledování doby odezvy a míry úspěšnosti volání externí části kódu. Výsledky se zobrazí v grafech závislostí na portálu. Následující fragment kódu se musí přidat všude, kde se provádí volání závislostí.

Poznámka:

Pro .NET a .NET Core můžete alternativně použít metodu TelemetryClient.StartOperation (extension), která vyplní DependencyTelemetry vlastnosti potřebné pro korelaci a některé další vlastnosti, jako je počáteční čas a doba trvání, takže nemusíte vytvářet vlastní časovač jako v následujících příkladech. Další informace najdete v části sledování odchozích závislostí v tématu Sledování vlastních operací pomocí sady 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
    });
}

Nezapomeňte, že sady SDK serveru zahrnují modul závislostí, který zjišťuje a sleduje určitá volání závislostí automaticky, například databázím a rozhraním REST API. Abyste mohli modul fungovat, musíte na server nainstalovat agenta.

V Javě je možné pomocí agenta Java Application Insights automaticky sledovat mnoho volání závislostí.

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

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

Závislosti v Log Analytics

V Application Insights Analytics se trackDependency volání zobrazí v dependencies tabulce.

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

dependencies
| summarize sum(itemCount) by target

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

dependencies
| join (requests) on operation_Id

Vyprázdnění dat

Sada SDK obvykle odesílá data v pevných intervalech, obvykle 30 sekund nebo kdykoli je vyrovnávací paměť plná, což je obvykle 500 položek. V některých případech můžete chtít vyrovnávací paměť vyprázdnit. Příkladem je, že používáte sadu SDK v aplikaci, která se vypne.

.NET

Při použití Flush()doporučujeme tento vzor:

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

Při použití FlushAsync()doporučujeme tento vzor:

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

Doporučujeme vždy vyprázdnit v rámci vypnutí aplikace, aby se zajistilo, že se telemetrie neztratí.

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.

Poznámka:

• Sady Java a JavaScript SDK se při vypnutí aplikace automaticky vyprázdní.
• Zkontrolujte konfiguraci Autoflush: Povolení autoflush ve vašem web.config souboru může vést ke snížení výkonu v aplikacích .NET instrumentovaných pomocí Application Insights. Když je povolená funkce autoflush, každé vyvolání metod vede k odesílání jednotlivých položek telemetrie jako samostatných webových System.Diagnostics.Trace.Trace* požadavků do služby příjmu dat. To může potenciálně způsobit vyčerpání sítě a úložiště na webových serverech. Pro zvýšení výkonu se doporučuje zakázat autoflush a také využít ServerTelemetryChannel, který je navržený pro efektivnější přenos telemetrických dat.

Ověření uživatelé

Ve webové aplikaci jsou uživatelé ve výchozím nastavení identifikováni soubory cookie . Pokud uživatel přistupuje k aplikaci z jiného počítače nebo prohlížeče, nebo pokud odstraní soubory cookie, může se počítat více než jednou.

Pokud se uživatelé přihlásí k 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>
}

Není nutné použít skutečné přihlašovací jméno uživatele. Musí to být jen ID, které je pro daného uživatele jedinečné. Nesmí obsahovat mezery ani žádný z znaků ,;=|.

ID uživatele je také nastaveno v souboru cookie relace a odesláno na server. Pokud je sada SDK serveru nainstalovaná, ověřené ID uživatele se odešle jako součást kontextových vlastností telemetrie klienta i serveru. Můžete ho pak filtrovat a vyhledávat.

Pokud vaše aplikace seskupí uživatele do účtů, můžete mu také předat identifikátor. Platí stejná omezení znaků.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

V Průzkumníku metrik můžete vytvořit graf, který počítá uživatele, ověřené a uživatelské účty.

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

Poznámka:

Vlastnost EnableAuthenticationTrackingJavaScript ve třídě ApplicationInsightsServiceOptions v sadě .NET Core SDK zjednodušuje konfiguraci JavaScriptu potřebnou k vložení uživatelského jména jako ID ověřování pro každé trasování odeslané sadou Application Insights JavaScript SDK.

Pokud je tato vlastnost nastavena na true, uživatelské jméno od uživatele v ASP.NET Core se vytiskne spolu s telemetrií na straně klienta. Z tohoto důvodu už není potřeba přidávat appInsights.setAuthenticatedUserContext ručně, protože už je vložený sadou SDK pro ASP.NET Core. ID ověřování se také odešle na server, na který sada SDK v .NET Core identifikuje a použije ho pro veškerou telemetrii na straně serveru, jak je popsáno v referenčních informacích k rozhraní JAVAScript API.

Pro javascriptové aplikace, které nefungují stejným způsobem jako ASP.NET Core MVC, jako jsou webové aplikace SPA, budete muset přidat appInsights.setAuthenticatedUserContext ručně.

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

Vlastnosti a měření můžete připojit k událostem, metrikám, zobrazením stránek, výjimkám a dalším telemetrickým datům.

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 poskytuje několik her, můžete ke každé události připojit název hry, abyste viděli, které hry jsou oblíbenější.

Délka řetězce je omezena na 8 192. Pokud chcete odesílat velké bloky dat, použijte parametr TrackTracezprávy .

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

Hodnoty metrik by měly být větší nebo rovny 0, aby se správně zobrazily.

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

Poznámka:

Ujistěte se, že ve vlastnostech nezapíšete identifikovatelné osobní údaje.

Alternativní způsob nastavení vlastností a metrik

Pokud je to pohodlnější, můžete shromažďovat 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);

Upozorňující

Nepoužívejte opakovaně stejnou instanci položky telemetrie (event v tomto příkladu) k opakovanému volání Track*() . Tento postup může způsobit odesílání telemetrie s nesprávnou konfigurací.

Vlastní měření a vlastnosti v Log Analytics

V Log Analytics se vlastní metriky a vlastnosti zobrazují v customMeasurements jednotlivých záznamech telemetrie a customDimensions atributech.

Pokud například do telemetrie požadavku přidáte vlastnost s názvem "game", tento dotaz spočítá výskyty různých hodnot "hry" 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:

• Když extrahujete hodnotu z objektu customDimensions NEBO customMeasurements JSON, má dynamický typ, takže ji musíte přetypovat tostring nebo todouble.
• Při zohlednění možnosti odběru vzorků nepoužívejte sum(itemCount) 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é berou v úvahu volby ve hře. K získání těchto informací použijte 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é napíšete, nastavte je v TelemetryClient instanci. Jsou připojené ke každé položce telemetrie odeslané z daného 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á volání telemetrie můžou přepsat výchozí hodnoty ve slovníkech vlastností.

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

Pokud chcete přidat vlastnosti do všech telemetrických dat, včetně dat ze standardních modulů kolekce, implementujte ITelemetryInitializer.

Ukázková, filtrovaná a procesní telemetrie

Viz Filtrování a předběžné zpracování telemetrie v sadě Application Insights SDK.

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. Příkladem je, pokud chcete odeslat vlastní TrackRequest data.

Node.js

telemetry.config.disableAppInsights = true;

Pokud chcete zakázat vybrané standardní kolektory, například čítače výkonu, požadavky HTTP nebo závislosti, 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();

Chcete-li tyto kolektory po inicializaci zakázat, použijte objekt Konfigurace: applicationInsights.Configuration.setAutoCollectRequests(false).

Vývojářský režim

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

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Pro Node.js můžete povolit vývojářský režim povolením interního protokolování prostřednictvím setInternalLogging a nastavením maxBatchSize 0, což způsobí, že se vaše telemetrie odešle hned po shromáždě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íč

Abyste se vyhnuli kombinování telemetrie z vývojových, testovacích a produkčních prostředí, můžete vytvořit samostatné prostředky Application Insights 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 ve svém kódu. Nastavte klíč v inicializační metodě, například global.aspx.cs ve službě ASP.NET:

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 toho, abyste ho doslova nakódovat do skriptu. Například na webové stránce vygenerované v aplikaci ASP.NET:

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, které se odesílají spolu se všemi telemetrickými daty. Obvykle jsou nastavené standardními moduly telemetrie, ale můžete je také nastavit sami. Příklad:

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

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

• Komponenta: Aplikace a její verze.
• Zařízení: Data o zařízení, na kterém je aplikace spuštěná. Ve webových aplikacích se jedná o server nebo klientské zařízení, ze kterého se telemetrie odesílá.
• InstrumentationKey: Prostředek Application Insights v Azure, kde se telemetrie zobrazuje. Je to obvykle vyzvednuto 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 tuto hodnotu nastavit tak, aby seskupily události dohromady.
  • 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čena z výpočtů v Průzkumníku metrik.
• Relace: Relace uživatele. ID je nastavené na vygenerovanou hodnotu, která se změní, když uživatel nějakou dobu nebyl aktivní.
• Uživatel: Informace o uživateli.

Omezení

Existuje několik omezení počtu metrik a událostí na aplikaci, tj. na klíč instrumentace. Omezení závisí na zvoleném cenovém plánu.

Prostředek	Výchozí omezení	Maximální limit	Notes
Celkem dat za den	100 GB	Obraťte se na podporu.	Můžete nastavit limit pro omezení dat. Pokud potřebujete více dat, můžete limit na portálu zvýšit až o 1 000 GB. U kapacit větších než 1 000 GB odešlete e-mail na AIDataCap@microsoft.comadresu .
Omezování	32 000 událostí za sekundu	Obraťte se na podporu.	Omezení se měří se po minutách.
Protokoly uchovávání dat	30 až 730 dní	730 dní	Tento prostředek je určený pro protokoly.
Metriky uchovávání dat	90 dní	90 dní	Tento prostředek je určený pro Průzkumníka metrik.
Uchovávání podrobných výsledků vícekrokového testu dostupnosti	90 dní	90 dní	Tento prostředek poskytuje podrobné výsledky každého kroku.
Maximální velikost položky telemetrie	64 kB	64 kB
Maximální počet položek telemetrie na dávku	64,000	64,000
Délka názvu vlastnosti a metriky	150	150	Viz schémata typů.
Délka řetězce hodnoty vlastnosti	8,192	8,192	Viz schémata typů.
Délka zprávy trasování a výjimky	32,768	32,768	Viz schémata typů.
Počet testů dostupnosti na prostředek Application Insights	100	100
Počet testů dostupnosti na skupinu prostředků	800	800	Viz Azure Resource Manager
Maximální počet přesměrování testů dostupnosti na test	10	10
Minimální frekvence testů dostupnosti	300 sekund		Vlastní frekvence testů nebo frekvence kratší než 5 minut vyžadují vlastní implementace trackAvailability .
Uchovávání dat v .NET Profileru a Snapshot Debuggeru	Dva týdny	Obraťte se na podporu. Maximální limit uchovávání je šest měsíců.
Data profileru .NET odeslaná za den	Bez omezení	Žádný limit.
Data snapshot Debuggeru odeslaná za den	30 snímků za den na monitorovanou aplikaci	Žádný limit.	Počet snímků shromážděných pro každou aplikaci je možné upravit prostřednictvím konfigurace.

Další informace o cenách a kvótách najdete v tématu Fakturace Application Insights.

Pokud se chcete vyhnout dosažení limitu rychlosti dat, použijte vzorkování.

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

Referenční dokumenty

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

Kód sady SDK

• .NET
• Balíčky Windows Serveru
• Java SDK
• Node.js SDK
• JavaScript SDK

Nejčastější dotazy

Tato část obsahuje odpovědi na běžné otázky.

Proč chybí telemetrická data?

TelemetryChannels ztratí telemetrii ve vyrovnávací paměti, pokud není vyprázdněná před vypnutím aplikace.

Aby nedošlo ke ztrátě dat, vyprázdněte TelemetryClient při vypnutí aplikace.

Další informace najdete v tématu Vyprázdnění dat.

Jaké výjimky můžou Track_() volat?

Nezaokrouhlovat. Nemusíte je zabalit do klauzulí try-catch. Pokud sada SDK narazí na problémy, protokoluje zprávy ve výstupu konzoly ladění a pokud se zprávy dostanou do diagnostického vyhledávání.

Existuje rozhraní REST API pro získání dat z portálu?

Ano, rozhraní API pro přístup k datům. Další způsoby extrakce dat zahrnují Power BI na prostředku založeném na pracovním prostoru.

Proč se moje volání vlastních událostí a rozhraní API metrik ignorují?

Sada Application Insights SDK není kompatibilní s automatickou opravou. Pokud je povolená automatická fáze, budou se ignorovat volání Track() vlastních událostí a rozhraní API metrik a dalších událostí.

Vypněte automatickou analýzu na webu Azure Portal na kartě Application Insights na stránce služby App Service nebo nastavte ApplicationInsightsAgent_EXTENSION_VERSION na disabledhodnotu .

Proč jsou počty v grafech vyhledávání a metrik nerovné?

Vzorkování snižuje počet položek telemetrie (jako jsou požadavky a vlastní události), které se odesílají z vaší aplikace na portál. Ve vyhledávání se zobrazí počet přijatých položek. V grafech metrik, které zobrazují počet událostí, se zobrazí počet původních událostí, ke kterým došlo.

Každá přenášená položka nese itemCount vlastnost, která ukazuje, kolik původních událostí tato položka představuje. Pokud chcete sledovat provoz vzorkování, můžete tento dotaz spustit v Log Analytics:

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

Jak můžu nastavit upozornění na událost?

Upozornění Azure jsou pouze na metrikách. Vytvořte vlastní metriku, která při výskytu události překročí prahovou hodnotu hodnoty. Pak nastavte upozornění na metriku. Oznámení dostanete pokaždé, když metrika překročí prahovou hodnotu v obou směrech. Dokud první přechod nedostanete oznámení, bez ohledu na to, jestli je počáteční hodnota vysoká nebo nízká. Vždy je latence několik minut.

Další kroky

• Vyhledávání událostí a protokolů