Rozhraní API služby 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. Telemetrii můžete odesílat ze zařízení a desktopových aplikací, webových klientů a webových serverů. Pomocí rozhraní API pro Přehledy základní telemetrie můžete odesílat vlastní události a metriky a vlastní verze standardní telemetrie. Toto rozhraní API je stejné rozhraní API, které používá standardní aplikace Přehledy kolektory dat.

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 této funkce. Přechod na připojovací řetězce , abyste mohli využívat nové funkce.

Souhrn rozhraní API

Základní rozhraní API je jednotné pro všechny platformy kromě několika variant, jako GetMetric je (jenom .NET).

Metoda Použití
TrackPageView Stránky, obrazovky, okna nebo formuláře
TrackEvent Akce uživatelů a další události Používá se ke sledování chování uživatelů nebo k monitorová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 k nim dochází ve vztahu k jiným událostem, a prozkoumání trasování zásobníku
TrackRequest Protokolování četnosti a doby trvání požadavků na server pro analýzu výkonu
TrackTrace Zprávy protokolu diagnostiky prostředků Můžete také zachytit 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 Přehledy SDK:

Získání instance TelemetryClient

Získejte instanci 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ískáte instanci TelemetryClient 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 automaticky zaznamenávají. Možná budete chtít vytvořit další instance pro další moduly TelemetryClient 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řipojené 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 Přehledy aplikace je vlastní událost datový bod, který můžete zobrazit v Průzkumníku metrik jako agregovaný počet a v diagnostickém vyhledávání jako jednotlivé výskyty. (Nesouvisí s MVC ani s jinou architekturou "events".)

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

Například v herní aplikaci 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ě Přehledy Protokoly nebo 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. itemCount==10 Například znamená, že 10 volání , trackEvent()proces vzorkování přenášen 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).

GetMetric

Informace o efektivním použ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 pro odesílání metrik. Metriky by měly být před odesláním vždy předem agregované v určitém časovém období. Pomocí jednoho z GetMetric(..) přetížení získejte objekt metriky pro přístup k funkcím 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).

Aplikační Přehledy 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ž varianty a trendy, takže statistické grafy jsou užitečné.

Pokud chcete odesílat metriky do Přehledy aplikace, 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 Přehledy aplikace.

    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. Podle toho bys volal TrackMetric dvakrát. Nejprve předáte hodnotu 3 a pak předáte hodnotu -2. Aplikace Přehledy 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 metrik je 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 režii na výkon odesláním méně datových bodů do Přehledy aplikace a přitom stále shromažďovat 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 customMetricsApplication Přehledy Analytics. 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í.

Zobrazení stránek

V zařízení nebo webové stránce se ve výchozím nastavení odesílá telemetrie zobrazení stránky při načtení každé obrazovky nebo stránky. Výchozí nastavení ale můžete změnit tak, aby sledovala zobrazení stránek více nebo v různých časech. Například v aplikaci, která zobrazuje karty nebo okna, můžete chtít sledovat stránku pokaždé, 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 když dojde k telemetrii zobrazení stránky, oživí se grafy uživatelů a relací.

Vlastní zobrazení stránek

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Pokud máte na různých stránkách HTML několik karet, 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 nahlášené jako doba načítání zobrazení stránky měří od doby, kdy prohlížeč odešle požadavek, dokud se nevyvolá 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í startu 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ě máte.

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 oblíbenost 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.

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

Doporučeným způsobem odeslání telemetrie požadavku 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á pro výjimky a další události, 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 Přehledy aplikace.

Při ručním sledování telemetrie je 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 typu, který zadáte. Odesílá položku telemetrie, když odstraníte operaci nebo pokud explicitně voláte StopOperation. Pokud použijete RequestTelemetry jako typ telemetrie, 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 .

Screenshot that shows the Related Items list.

Další informace o sledování vlastních operací najdete v tématu Sledování vlastních operací pomocí sady Application Přehledy .NET SDK.

Žádosti v Log Analytics

V Přehledy Analytics aplikace se žádosti zobrazí v requests tabulce.

Pokud je vzorkování v provozu, vlastnost itemCount zobrazí 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 Přehledy aplikace:

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

Ve službě Application Přehledy Analytics se výjimky zobrazují v exceptions tabulce.

Pokud je vzorkování v provozu, vlastnost itemCount zobrazí 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 například následující kód:

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 můžete od sebe odtáhnout details strukturu, abyste získali více. 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 "popis cesty" do Přehledy aplikace. 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ě aplikace Přehledy agenta Javy automaticky zasílají 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
})

Zapíše diagnostickou událost, například zadávání nebo opuštění metody.

Parametr Popis
message Diagnostická data. Může být mnohem delší než název.
properties Mapa řetězce na řetězec Další data slouží 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 umístit relativně dlouhá data. Můžete tam například zakódovat data POST.

Do zprávy můžete také přidat úroveň závažnosti. 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ě Hledat 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 aplikaci Přehledy Analytics se volání TrackTrace zobrazí v traces tabulce.

Pokud je vzorkování v provozu, itemCount vlastnost zobrazuje hodnotu větší než 1. itemCount==10 Například znamená, že 10 volání , trackTrace()proces vzorkování přenášen 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 musí být přidán 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 (rozšíření), která vyplní DependencyTelemetry vlastnosti potřebné pro korelaci a některé další vlastnosti, jako je čas zahájení 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 o sledování odchozích závislostí ve sledování vlastních operací pomocí sady Application Přehledy .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
    });
}

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

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

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

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

Závislosti v Log Analytics

V aplikaci Přehledy AnalyticstrackDependency se volání zobrazí v dependencies tabulce.

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

dependencies
| summarize sum(itemCount) by target

Pokud chcete přidružit závislosti ke svým 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 vždy, když 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()

Doporučujeme vždy vyprázdnit jako součást vypnutí aplikace, aby se zajistilo, že telemetrie nebude ztracena.

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 automaticky vyprázdní při vypnutí aplikace.

Skupina Authenticated Users

Ve webové aplikaci se uživatelé ve výchozím nastavení identifikují pomocí souborů 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í se jednat pouze o ID, které je jedinečné pro daného uživatele. Nesmí obsahovat mezery ani žádné znaky ,;=|.

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

Pokud vaše aplikace seskupí uživatele do účtů, můžete také předat identifikátor účtu. 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 datové body klienta 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é aplikací Přehledy 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 by přidání appInsights.setAuthenticatedUserContext ručně nebylo potřeba, protože už je vložena sadou SDK pro ASP.NET Core. ID ověřování se odešle také na server, na kterém sada SDK v .NET Core identifikuje a použije ho pro libovolnou telemetrii na straně serveru, jak je popsáno v referenčních informacích k rozhraní JAVAScript API.

U aplikací JavaScriptu, 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 segmentování 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 zprávy .TrackTrace

Metriky jsou číselné hodnoty, které lze zobrazit graficky. Můžete například chtít zjistit, jestli se postupně zvyšuje skóre, které hráči dosáhli. 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 rovno 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 nezaregistrujete 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);

Upozornění

Opakovaně nepoužívejte stejnou instanci položky telemetrie (event v tomto příkladu) k vícenásobnému volání Track*() . Tento postup může způsobit odeslá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 atributy.

Pokud například přidáte vlastnost s názvem "hra" do telemetrie požadavku, tento dotaz spočítá výskyty různých hodnot "hry" a zobrazí průměr vlastní metriky "skóre":

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

Všimněte si, že:

  • Když extrahujete hodnotu z customDimensions kódu NEBO customMeasurements JSON, má dynamický typ, takže je nutné ji tostring přetypovat nebo todouble.
  • Pokud chcete zohlednit možnost vzorkování, nepoužívejte sum(itemCount)count().

Události časování

Někdy chcete grafovat, jak dlouho trvá provedení akce. Můžete například chtít vědět, jak dlouho budou uživatelé brát 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é píšete, nastavte je v TelemetryClient instanci. Jsou připojeny 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í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ů kolekce, implementujte ITelemetryInitializer.

Ukázka, filtrování a zpracování telemetrie

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

Přidání vlastností do telemetrie implementací ITelemetryInitializer. Můžete například přidat čísla verzí nebo hodnoty počítané z jiných vlastností.

Filtrování může upravit nebo zahodit telemetrii před odesláním ze sady SDK implementací ITelemetryProcessor. Určujete, co se odesílají nebo zahodí, ale musíte zohlednit vliv na metriky. V závislosti na tom, jak zahodíte položky, může dojít ke ztrátě možnosti navigace mezi souvisejícími položkami.

Vzorkování je zabalené řešení, které snižuje objem dat odesílaných z vaší aplikace na portál. To provede, aniž by to mělo vliv na zobrazené metriky. A to dělá, aniž by to ovlivnilo vaši schopnost diagnostikovat problémy tím, že přejdete mezi souvisejícími položkami, jako jsou výjimky, požadavky a zobrazení stránek.

Další informace najdete v tématu Filtrování a předběžné zpracování telemetrie v sadě Application Přehledy 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, v době inicializace zřetězte metody konfigurace do kódu inicializace 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).

Režim vývojáře

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

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

V případě 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 posílají 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 aplikace 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 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 můžete chtít nastavit ho ze stavu webového serveru, a ne doslova ho zakó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 odesílané 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 nastavíte některou z těchto hodnot sami, zvažte odebrání příslušného řádku z ApplicationInsights.config , aby se hodnoty a standardní hodnoty nezaměňují.

  • 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 aplikace Přehledy v Azure, kde se telemetrie zobrazuje. Obvykle je to 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.
    • SyntetickýSource: 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čeno 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 určitá omezení počtu metrik a událostí pro aplikaci, tj. na klíč instrumentace. Omezení závisí na zvoleném cenovém plánu.

Prostředek Výchozí omezení Maximální omezení Poznámky
Celkem dat za den 100 GB Kontaktujte podporu. Objem dat jde snížit nastavením limitu. Pokud potřebujete další data, můžete na portálu zvýšit limit až o 1 000 GB. V případě kapacit větších než 1 000 GB odešlete e-mail .AIDataCap@microsoft.com
Throttling 32 000 událostí za sekundu Kontaktujte 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ů testu dostupnosti ve více krocích 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ů.
Testy dostupnosti – počet na aplikaci 100 100
Profiler a uchovávání dat snímků Dva týdny Obraťte se na podporu. Maximální limit uchovávání je šest měsíců.
Data profileru odeslaná za den Bez limitu Bez limitu
Snímková data odeslaná za den 30 snímků za den na monitorovanou aplikaci Bez limitu 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 Přehledy aplikací.

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í dat a ochrana osobních údajů.

Referenční dokumenty

Kód sady SDK

Dotazy

Další kroky