Sdílet prostřednictvím

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

Upozornění

Pro nové aplikace nebo zákazníky doporučujeme použití Azure Monitor OpenTelemetry Distro ke zlepšení služby Azure Monitor Application Insights. Distribuce OpenTelemetry služby Azure Monitor poskytuje podobné funkce a prostředí jako sada Application Insights SDK. Ze sady Application Insights SDK je možné migrovat pomocí průvodců migrací pro .NET, Node.js a Python, ale stále pracujeme na přidání několika dalších funkcí pro zpětnou kompatibilitu.

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é jako to, které používají standardní kolektory dat Application Insights.

Poznámka:

Podpora pro příjem instrumentačních klíčů 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 je GetMetric (pouze .NET).

metoda Používá se pro
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 Sledujte, kde se vyskytují ve vztahu k jiným událostem, a prozkoumejte 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:

Získejte instanci TelemetryClient

Získejte instanci TelemetryClient (kromě v JavaScriptu na webových stránkách):

V případě aplikací ASP.NET Core a aplikací Non-HTTP/Worker pro .NET/.NET Core získejte instanci TelemetryClient z kontejneru injektování 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 vláknově bezpečný.

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 projektech Node.js můžete použít new applicationInsights.TelemetryClient(instrumentationKey?) pro vytvoření nové instance. 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' v rámci frameworku.)

Vložte do svého kódu volání TrackEvent, abyste počítali 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 tabulce customEvents na kartě Protokoly Application Insights nebo v uživatelském prostředí. Události můžou pocházet z trackEvent(..) nebo z modulu plug-in automatické kolekce Click Analytics.

Pokud je vzorkování aktivní, itemCount vlastnost zobrazuje hodnotu větší než 1. Například itemCount==10 znamená, že z 10 volání trackEvent() byl procesem vzorkování přenesen 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.

Získat metriku

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. Například můžete sledovat 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 aplikaci Application Insights Analytics. Každý řádek představuje volání trackMetric(..) ve vaší aplikaci.

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

Poznámka:

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

Zobrazení stránek

Při načtení každé obrazovky nebo stránky v zařízení či webové aplikaci se 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.

Uživatelská a relační data jsou odesílána jako vlastnosti spolu se zobrazeními stránek, takže grafy uživatelů a relací ožívají, když jsou telemetrie zobrazení stránek.

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

Časování zobrazení stránek

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í načasování zobrazení stránky 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, spojuje 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 zjistit, jak dlouho trvá prohlížeči 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

Žádost o sledování

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 takový, kdy 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ž ukončí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 provozu se stávají dceřinými položkami takové operace. Kontexty operací mohou být vnořené.

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

Snímek obrazovky se seznamem Souvisejících položek

Pro více informací o sledování vlastních operací viz Jak sledovat vlastní operace pomocí Application Insights .NET SDK.

Požadavky v Log Analytics

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

Pokud je vzorkování aktivní, itemCount vlastnost zobrazuje hodnotu větší než 1. Například itemCount==10 znamená, že z 10 volání trackRequest() byl procesem vzorkování přenesen 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:

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ě:

({
    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í aktivní, itemCount vlastnost zobrazuje hodnotu větší než 1. Například itemCount==10 znamená, že z 10 volání trackException() byl procesem vzorkování přenesen 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 propojení:

exceptions
| join (requests) on operation_Id

TrackTrace

Použijte TrackTrace k diagnostice problémů odesláním "drobečkové navigace" 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 Java Application Insights Java agent 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
})

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í nastavení 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 jinou telemetrii můžete přidat hodnoty vlastností, které vám pomůžou filtrovat nebo vyhledávat různé sady tras. 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í zobrazí v tabulce TrackTrace.

Pokud je vzorkování aktivní, itemCount vlastnost zobrazuje hodnotu větší než 1. Například itemCount==10 znamená, že z 10 volání trackTrace() byl procesem vzorkování přenesen 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

Volání TrackDependency použijte ke sledování dob 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 části Potlačení konkrétní automaticky sbírané 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 itemCount==10 znamená, že z 10 volání trackDependency() byl procesem vzorkování přenesen 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 spojení:

dependencies
| join (requests) on operation_Id

Proplachová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:

  • SDK pro Java a JavaScript se při vypnutí aplikace automaticky vyčistí.
  • 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:

Břitva

@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é uloženo v relačním souboru cookie 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í bude také odesláno na server, kde ho sada SDK v .NET Core identifikuje a použije pro veškerou telemetrii na straně serveru, jak je popsáno v referenci 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 o používání. 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 zprávy TrackTrace.

Metriky jsou číselné hodnoty, které lze graficky prezentovat. Můžete například chtít zjistit, jestli se skóre, kterých vaši 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);

Varování

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

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

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ů používejte sum(itemCount), nikoliv count().

Časové události

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 mohou přepsat výchozí hodnoty ve slovnících 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, jako jsou čítače výkonu, požadavky HTTP nebo závislosti, odstraňte nebo zakomentujte příslušné řádky v ApplicationInsights.config. Například pokud chcete odeslat vlastní TrackRequest data.

Node.js

telemetry.config.disableAppInsights = true;

Chcete-li zakázat vybrané standardní kolektory, například čítače výkonu, HTTP požadavky nebo závislosti, během inicializace zřetězte konfigurační metody 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é zrychlit telemetrii prostřednictvím potrubí, abyste mohli okamžitě vidět 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 maxBatchSize0, 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);
    }

Telemetrický kontext

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. Obvykle se to vyzvedává z ApplicationInsights.config.
  • Umístění: Zeměpisné umístění zařízení.
  • Operace: Aktuální HTTP požadavek ve webových aplikacích. 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.
  • Sezení: Uživatelské sezení. 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 Poznámky
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 .
Škrcení 32 000 událostí za sekundu Obraťte se na podporu. Limit je měřen během jedné minuty.
Protokoly uchovávání dat 30 až 730 dní 730 dní Tento zdroj 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.
Podrobné uchovávání 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 sto padesát sto padesát Viz schémata typů.
Délka řetězce hodnoty vlastnosti 8,192 8,192 Viz schémata typů.
Délka zprávy sledování a výjimky 32,768 32,768 Viz schémata typů.
Počet testů dostupnosti na zdroj 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í v testech dostupnosti na jeden 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 .NET profileru odeslaná denně 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

Kód sady SDK

Další kroky