Interfejs API usługi Application Insights dla niestandardowych zdarzeń i metryk

Wstaw kilka wierszy kodu w aplikacji, aby dowiedzieć się, co robią z nim użytkownicy, lub pomóc zdiagnozować problemy. Dane telemetryczne można wysyłać z urządzeń i aplikacji klasycznych, klientów internetowych i serwerów internetowych. Użyj podstawowego interfejsu API telemetrii usługi Application Insights , aby wysyłać niestandardowe zdarzenia i metryki oraz własne wersje standardowej telemetrii. Ten interfejs API jest tym samym interfejsem API, którego używają standardowi moduły zbierające dane usługi Application Insights.

Uwaga

31 marca 2025 r. zostanie zakończone świadczenie pomocy technicznej dla pozyskiwania klucza instrumentacji. Pozyskiwanie klucza instrumentacji będzie nadal działać, ale nie udostępnimy już aktualizacji ani obsługi funkcji. Przejście do parametrów połączenia w celu skorzystania z nowych możliwości.

Podsumowanie interfejsu API

Podstawowy interfejs API jest jednolity na wszystkich platformach, oprócz kilku odmian, takich jak GetMetric (tylko platforma.NET).

Metoda Sposób użycia
TrackPageView Strony, ekrany, okienka lub formularze.
TrackEvent Akcje użytkownika i inne zdarzenia. Służy do śledzenia zachowania użytkownika lub monitorowania wydajności.
GetMetric Metryki zerowe i wielowymiarowe, centralnie skonfigurowane agregacje, tylko język C#.
TrackMetric Pomiary wydajności, takie jak długości kolejki, nie są związane z określonymi zdarzeniami.
TrackException Rejestrowanie wyjątków dla diagnostyki. Śledzenie miejsca ich występowania w odniesieniu do innych zdarzeń i badanie śladów stosu.
TrackRequest Rejestrowanie częstotliwości i czasu trwania żądań serwera na potrzeby analizy wydajności.
TrackTrace Komunikaty dziennika diagnostycznego zasobów. Możesz również przechwytywać dzienniki innych firm.
TrackDependency Rejestrowanie czasu trwania i częstotliwości wywołań do składników zewnętrznych, od których zależy aplikacja.

Do większości tych wywołań telemetrycznych można dołączyć właściwości i metryki .

Przed rozpoczęciem

Jeśli nie masz jeszcze odwołania do zestawu SDK usługi Application Insights:

Pobieranie wystąpienia telemetriiClient

Pobierz wystąpienie TelemetryClient (z wyjątkiem języka JavaScript na stronach internetowych):

W przypadku aplikacji ASP.NET Core i aplikacji innych niż HTTP/Worker dla aplikacji .NET/.NET Core pobierz wystąpienie z TelemetryClient kontenera iniekcji zależności, jak wyjaśniono w odpowiedniej dokumentacji.

Jeśli używasz Azure Functions v2+ lub Azure WebJobs w wersji 3 lub nowszej, zobacz Monitorowanie Azure Functions.

C#

private TelemetryClient telemetry = new TelemetryClient();

Jeśli zostanie wyświetlony komunikat informujący o tym, że ta metoda jest przestarzała, zobacz microsoft/ApplicationInsights-dotnet#1152 , aby uzyskać więcej informacji.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient jest bezpieczny wątkiem.

W przypadku projektów ASP.NET i Java przychodzące żądania HTTP są automatycznie przechwytywane. Możesz utworzyć więcej wystąpień dla innych modułów TelemetryClient aplikacji. Na przykład może istnieć jedno TelemetryClient wystąpienie klasy oprogramowania pośredniczącego w celu zgłaszania zdarzeń logiki biznesowej. Możesz ustawić właściwości, takie jak UserId i DeviceId zidentyfikować maszynę. Te informacje są dołączone do wszystkich zdarzeń wysyłanych przez wystąpienie.

C#

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

Java

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

W projektach Node.js można utworzyć new applicationInsights.TelemetryClient(instrumentationKey?) nowe wystąpienie. Zalecamy to podejście tylko w przypadku scenariuszy, które wymagają izolowanej konfiguracji z pojedynczego elementu defaultClient.

TrackEvent

W usłudze Application Insights zdarzenie niestandardowe to punkt danych, który można wyświetlić w Eksploratorze metryk jako zagregowaną liczbę i w wyszukiwaniu diagnostycznym jako pojedyncze wystąpienia. (Nie jest to związane z mvC ani innymi strukturami "events".

Wstaw wywołania TrackEvent w kodzie, aby zliczyć różne zdarzenia. Możesz na przykład śledzić, jak często użytkownicy wybierają określoną funkcję. Możesz też wiedzieć, jak często osiągają określone cele lub popełniają określone błędy.

Na przykład w aplikacji do gry wyślij zdarzenie za każdym razem, gdy użytkownik wygra grę:

JavaScript

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

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

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

Zdarzenia niestandardowe w usłudze Log Analytics

Dane telemetryczne są dostępne w customEvents tabeli na karcie Dzienniki usługi Application Insights lub w środowisku użycia. Zdarzenia mogą pochodzić z trackEvent(..)lub wtyczki automatycznej zbierania analizy kliknięć.

Jeśli próbkowanie jest w operacji, itemCount właściwość wyświetla wartość większą niż 1. Na przykład oznacza to, itemCount==10 że z 10 wywołań do trackEvent(), proces próbkowania przesłany tylko jeden z nich. Aby uzyskać poprawną liczbę zdarzeń niestandardowych, użyj kodu takiego jak customEvents | summarize sum(itemCount).

Uwaga

element ItemCount ma minimalną wartość jedną; sam rekord reprezentuje wpis.

GetMetric

Aby dowiedzieć się, jak efektywnie używać GetMetric() wywołania do przechwytywania wstępnie zagregowanych metryk dla aplikacji .NET i .NET Core, zobacz Kolekcje metryk niestandardowych na platformie .NET i platformie .NET Core.

Śledzenie metryk

Uwaga

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric nie jest preferowaną metodą wysyłania metryk. Metryki powinny być zawsze wstępnie zagregowane w okresie przed wysłaniem. Użyj jednego z GetMetric(..) przeciążeń, aby uzyskać obiekt metryki na potrzeby uzyskiwania dostępu do funkcji agregacji wstępnej zestawu SDK.

Jeśli implementujesz własną logikę wstępnego agregacji, możesz użyć TrackMetric() metody do wysyłania wynikowych agregacji. Jeśli aplikacja wymaga wysyłania oddzielnego elementu telemetrii przy każdej okazji bez agregacji w czasie, prawdopodobnie masz przypadek użycia danych telemetrycznych zdarzeń. Zobacz: .

Usługa Application Insights może wykresować metryki, które nie są dołączone do określonych zdarzeń. Można na przykład monitorować długość kolejki w regularnych odstępach czasu. W przypadku metryk poszczególne miary są mniej interesujące niż odmiany i trendy, dlatego przydatne są wykresy statystyczne.

Aby wysłać metryki do usługi Application Insights, możesz użyć interfejsu TrackMetric(..) API. Istnieją dwa sposoby wysyłania metryki:

  • Pojedyncza wartość. Za każdym razem, gdy wykonujesz pomiar w aplikacji, wysyłasz odpowiednią wartość do usługi Application Insights.

    Załóżmy na przykład, że masz metrykę opisową liczbę elementów w kontenerze. W określonym przedziale czasu najpierw umieścisz trzy elementy w kontenerze, a następnie usuniesz dwa elementy. W związku z tym wywołasz dwa razy TrackMetric . Najpierw należy przekazać wartość 3 , a następnie przekazać wartość -2. Usługa Application Insights przechowuje obie wartości.

  • Agregacja. Podczas pracy z metrykami każda miara jest rzadko interesująca. Zamiast tego ważne jest podsumowanie tego, co wydarzyło się w określonym przedziale czasu. Takie podsumowanie jest nazywane agregacją.

    W poprzednim przykładzie suma zagregowanej metryki dla tego okresu wynosi 1 , a liczba wartości metryki to 2. W przypadku korzystania z podejścia agregacji należy wywołać TrackMetric tylko raz w danym okresie i wysłać wartości zagregowane. Zalecamy takie podejście, ponieważ może znacznie zmniejszyć koszty i wydajność, wysyłając mniej punktów danych do usługi Application Insights, jednocześnie zbierając wszystkie istotne informacje.

Przykłady pojedynczej wartości

Aby wysłać pojedynczą wartość metryki:

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

Metryki niestandardowe w usłudze Log Analytics

Dane telemetryczne są dostępne w tabeli w customMetrics usłudze Application Insights Analytics. Każdy wiersz reprezentuje wywołanie metody trackMetric(..) w aplikacji.

  • valueSum: suma pomiarów. Aby uzyskać średnią wartość, podziel na wartość valueCount.
  • valueCount: liczba miar zagregowanych w tym trackMetric(..) wywołaniu.

Uwaga

wartość valueCount ma minimalną wartość jedną; sam rekord reprezentuje wpis.

Widoki stron

W aplikacji urządzenia lub strony internetowej dane telemetryczne widoku strony są domyślnie wysyłane po załadowaniu każdego ekranu lub strony. Możesz jednak zmienić ustawienie domyślne, aby śledzić widoki stron w więcej lub różnych godzinach. Na przykład w aplikacji, która wyświetla karty lub okienka, możesz śledzić stronę za każdym razem, gdy użytkownik otworzy nowe okienko.

Dane użytkownika i sesji są wysyłane jako właściwości wraz z widokami stron, więc wykresy użytkownika i sesji są aktywne, gdy są wyświetlane dane telemetryczne widoku strony.

Niestandardowe widoki stron

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Jeśli masz kilka kart na różnych stronach HTML, możesz również określić adres URL:

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

Widoki stron chronometrażu

Domyślnie czasy zgłaszane jako czas ładowania widoku strony są mierzone od momentu wysłania żądania przez przeglądarkę do momentu wywołania zdarzenia ładowania strony przeglądarki.

Zamiast tego można wykonać następujące czynności:

  • Ustaw jawny czas trwania wywołania trackPageView : appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Użyj wywołań startTrackPage chronometrażu widoku strony i stopTrackPage.

JavaScript

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

...

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

Nazwa używana jako pierwszy parametr kojarzy wywołania uruchamiania i zatrzymywania. Wartość domyślna to bieżąca nazwa strony.

Wynikowe czasy ładowania strony wyświetlane w Eksploratorze metryk pochodzą z interwału między wywołaniami uruchamiania i zatrzymywania. To do Ciebie, jaki interwał faktycznie nadszedł.

Telemetria strony w usłudze Log Analytics

W usłudze Log Analytics dwie tabele pokazują dane z operacji przeglądarki:

  • pageViews: zawiera dane dotyczące adresu URL i tytułu strony.
  • browserTimings: zawiera dane dotyczące wydajności klienta, takie jak czas potrzebny na przetwarzanie danych przychodzących.

Aby dowiedzieć się, jak długo trwa przetwarzanie różnych stron w przeglądarce:

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

Aby odkryć popularność różnych przeglądarek:

pageViews
| summarize count() by client_Browser

Aby skojarzyć widoki stron z wywołaniami AJAX, dołącz do zależności:

pageViews
| join (dependencies) on operation_Id

TrackRequest

Zestaw SDK serwera używa TrackRequest do rejestrowania żądań HTTP.

Możesz również wywołać je samodzielnie, jeśli chcesz symulować żądania w kontekście, w którym nie masz uruchomionego modułu usługi internetowej.

Zalecanym sposobem wysyłania danych telemetrycznych żądania jest to, gdzie żądanie działa jako kontekst operacji.

Kontekst operacji

Elementy telemetryczne można skorelować razem, kojarząc je z kontekstem operacji. Standardowy moduł śledzenia żądań wykonuje tę funkcję w przypadku wyjątków i innych zdarzeń wysyłanych podczas przetwarzania żądania HTTP. W obszarze Wyszukiwanie i analiza można łatwo znaleźć wszystkie zdarzenia skojarzone z żądaniem przy użyciu identyfikatora operacji.

Aby uzyskać więcej informacji na temat korelacji, zobacz Korelacja telemetrii w usłudze Application Insights.

W przypadku ręcznego śledzenia danych telemetrycznych najprostszym sposobem zapewnienia korelacji telemetrii jest użycie tego wzorca:

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.

Wraz z ustawieniem kontekstu StartOperation operacji tworzy element telemetrii określonego typu. Wysyła on element telemetrii podczas usuwania operacji lub jawnie wywołania StopOperationmetody . Jeśli używasz RequestTelemetry jako typu telemetrii, jego czas trwania jest ustawiony na interwał czasu między rozpoczęciem a zatrzymaniem.

Elementy telemetryczne zgłaszane w zakresie operacji stają się elementami podrzędnym takiej operacji. Konteksty operacji można zagnieżdżać.

W obszarze Wyszukiwanie kontekst operacji służy do tworzenia listy Powiązane elementy .

Zrzut ekranu przedstawiający listę Powiązane elementy.

Aby uzyskać więcej informacji na temat śledzenia operacji niestandardowych, zobacz Śledzenie operacji niestandardowych za pomocą zestawu SDK platformy .NET usługi Application Insights.

Żądania w usłudze Log Analytics

W usłudze Application Insights Analytics żądania są wyświetlane w requests tabeli.

Jeśli próbkowanie jest w operacji, itemCount właściwość wyświetla wartość większą niż 1. Na przykład oznacza to, itemCount==10 że z 10 wywołań do trackRequest(), proces próbkowania przesłany tylko jeden z nich. Aby uzyskać poprawną liczbę żądań i średni czas trwania podzielony na segmenty według nazw żądań, użyj kodu, takiego jak:

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

TrackException

Wysyłanie wyjątków do usługi Application Insights:

Raporty obejmują ślady stosu.

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

Zestawy SDK automatycznie przechwytują wiele wyjątków, więc nie zawsze trzeba wywoływać TrackException jawnie:

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

Wyjątki w usłudze Log Analytics

W usłudze Application Insights Analytics wyjątki są wyświetlane w exceptions tabeli.

Jeśli próbkowanie jest w operacji, itemCount właściwość wyświetla wartość większą niż 1. Na przykład oznacza to, itemCount==10 że z 10 wywołań do trackException(), proces próbkowania przesłany tylko jeden z nich. Aby uzyskać poprawną liczbę wyjątków podzielonych na segmenty według typu wyjątku, użyj kodu, takiego jak:

exceptions
| summarize sum(itemCount) by type

Większość ważnych informacji o stosie jest już wyodrębniona do oddzielnych zmiennych, ale możesz rozciągnąć details strukturę, aby uzyskać więcej. Ponieważ ta struktura jest dynamiczna, należy rzutować wynik na oczekiwany typ. Przykład:

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

Aby skojarzyć wyjątki z powiązanymi żądaniami, użyj sprzężenia:

exceptions
| join (requests) on operation_Id

TrackTrace

Użyj TrackTrace polecenia , aby pomóc zdiagnozować problemy, wysyłając "ślad do stron nadrzędnych" do usługi Application Insights. Fragmenty danych diagnostycznych można wysyłać i sprawdzać w wyszukiwaniu diagnostycznym.

W kartach dziennika platformy .NET użyj tego interfejsu API, aby wysyłać dzienniki innych firm do portalu.

W języku Java agent języka Java usługi Application Insights automatycznie wykonuje i wysyła dzienniki do portalu.

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

Klient/przeglądarka — JavaScript

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

Rejestruje zdarzenie diagnostyczne, takie jak wprowadzanie lub opuszczanie metody.

Parametr Opis
message Dane diagnostyczne. Może być znacznie dłuższa niż nazwa.
properties Mapuj ciąg na ciąg. Więcej danych służy do filtrowania wyjątków w portalu. Wartości domyślne są puste.
severityLevel Obsługiwane wartości: SeverityLevel.ts.

Możesz wyszukiwać zawartość wiadomości, ale w przeciwieństwie do wartości właściwości, nie można go filtrować.

Limit rozmiaru właściwości message jest znacznie wyższy niż limit właściwości. Zaletą TrackTrace jest to, że można umieścić stosunkowo długie dane w komunikacie. Na przykład możesz kodować tam dane POST.

Możesz również dodać poziom ważności do wiadomości. Podobnie jak inne dane telemetryczne, można dodać wartości właściwości, aby ułatwić filtrowanie lub wyszukiwanie różnych zestawów śladów. Przykład:

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

W obszarze Wyszukiwanie można łatwo odfiltrować wszystkie komunikaty określonego poziomu ważności powiązanego z określoną bazą danych.

Ślady w usłudze Log Analytics

W usłudze Application Insights Analytics wywołania, które TrackTrace mają być wyświetlane w traces tabeli.

Jeśli próbkowanie jest w operacji, itemCount właściwość wyświetla wartość większą niż 1. Na przykład oznacza to, itemCount==10 że z 10 wywołań do trackTrace(), proces próbkowania przesłany tylko jeden z nich. Aby uzyskać poprawną liczbę wywołań śledzenia, użyj kodu, takiego jak traces | summarize sum(itemCount).

TrackDependency

TrackDependency Użyj wywołania, aby śledzić czasy odpowiedzi i wskaźniki powodzenia wywołań do zewnętrznego fragmentu kodu. Wyniki są wyświetlane na wykresach zależności w portalu. Poniższy fragment kodu należy dodać wszędzie tam, gdzie jest wykonywane wywołanie zależności.

Uwaga

W przypadku platform .NET i .NET Core możesz również użyć TelemetryClient.StartOperation metody (rozszerzenia), która wypełnia DependencyTelemetry właściwości wymagane do korelacji i innych właściwości, takich jak czas rozpoczęcia i czas trwania, więc nie musisz tworzyć niestandardowego czasomierza, tak jak w poniższych przykładach. Aby uzyskać więcej informacji, zobacz sekcję dotyczącą śledzenia zależności wychodzących w temacie Śledzenie operacji niestandardowych za pomocą zestawu SDK platformy .NET usługi Application Insights.

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

Pamiętaj, że zestawy SDK serwera zawierają moduł zależności , który odnajduje i śledzi niektóre wywołania zależności automatycznie, na przykład do baz danych i interfejsów API REST. Aby wykonać pracę modułu, musisz zainstalować agenta na serwerze.

W języku Java wiele wywołań zależności można automatycznie śledzić przy użyciu agenta Java usługi Application Insights.

To wywołanie jest używane, jeśli chcesz śledzić wywołania, których automatyczne śledzenie nie przechwyci.

Aby wyłączyć standardowy moduł śledzenia zależności w języku C#, edytuj ApplicationInsights.config i usuń odwołanie do DependencyCollector.DependencyTrackingTelemetryModule. W przypadku języka Java zobacz Pomijanie określonych autokolektowanych danych telemetrycznych.

Zależności w usłudze Log Analytics

W usłudze Application Insights AnalyticstrackDependency wywołania są wyświetlane w dependencies tabeli.

Jeśli próbkowanie jest wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład oznacza to, itemCount==10 że z 10 wywołań do trackDependency(), proces próbkowania przesłany tylko jeden z nich. Aby uzyskać poprawną liczbę zależności podzielonych na segmenty według składnika docelowego, użyj kodu, takiego jak:

dependencies
| summarize sum(itemCount) by target

Aby skojarzyć zależności z powiązanymi żądaniami, użyj sprzężenia:

dependencies
| join (requests) on operation_Id

Opróżnianie danych

Zwykle zestaw SDK wysyła dane w stałych odstępach czasu, zazwyczaj 30 sekund lub za każdym razem, gdy bufor jest pełny, czyli zazwyczaj 500 elementów. W niektórych przypadkach może być konieczne opróżnienie buforu. Przykładem jest użycie zestawu SDK w aplikacji, która zostanie zamknięta.

.NET

W przypadku korzystania z Flush()programu zalecamy następujący wzorzec:

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

W przypadku korzystania z FlushAsync()programu zalecamy następujący wzorzec:

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

Zalecamy zawsze opróżnianie w ramach zamknięcia aplikacji, aby zagwarantować, że dane telemetryczne nie zostaną utracone.

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

Funkcja jest asynchroniczna dla kanału telemetrii serwera.

Uwaga

Zestawy SDK java i JavaScript są automatycznie opróżniane po zamknięciu aplikacji.

Uwierzytelnieni użytkownicy

W aplikacji internetowej użytkownicy są domyślnie identyfikowani przez pliki cookie . Użytkownik może być liowany więcej niż raz, jeśli uzyskuje dostęp do aplikacji z innej maszyny lub przeglądarki lub jeśli usunie pliki cookie.

Jeśli użytkownicy logowali się do aplikacji, możesz uzyskać dokładniejszą liczbę, ustawiając uwierzytelniony identyfikator użytkownika w kodzie przeglądarki:

JavaScript

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

Na przykład w aplikacji internetowej MVC ASP.NET:

Razor

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

Nie trzeba używać rzeczywistej nazwy logowania użytkownika. Musi to być tylko identyfikator, który jest unikatowy dla tego użytkownika. Nie może zawierać spacji ani znaków ,;=|.

Identyfikator użytkownika jest również ustawiany w pliku cookie sesji i wysyłany do serwera. Jeśli zestaw SDK serwera jest zainstalowany, uwierzytelniony identyfikator użytkownika jest wysyłany jako część właściwości kontekstu telemetrii klienta i serwera. Następnie możesz filtrować i wyszukiwać.

Jeśli aplikacja grupuje użytkowników na kontach, możesz również przekazać identyfikator konta. Obowiązują te same ograniczenia znaków.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

W Eksploratorze metryk można utworzyć wykres zliczający użytkowników, uwierzytelnione i konta użytkowników.

Możesz również wyszukać punkty danych klienta z określonymi nazwami użytkowników i kontami.

Uwaga

Właściwość EnableAuthenticationTrackingJavaScript w klasie ApplicationInsightsServiceOptions w zestawie SDK platformy .NET Core upraszcza konfigurację języka JavaScript wymaganą do wstrzyknięcia nazwy użytkownika jako identyfikatora uwierzytelniania dla każdego śledzenia wysyłanego przez zestaw SDK języka JavaScript usługi Application Insights.

Po ustawieniu tej właściwości na truewartość , nazwa użytkownika od użytkownika w ASP.NET Core jest drukowana wraz z telemetrią po stronie klienta. Z tego powodu dodawanie appInsights.setAuthenticatedUserContext ręcznie nie byłoby już potrzebne, ponieważ jest już wstrzykiwane przez zestaw SDK dla ASP.NET Core. Identyfikator uwierzytelniania zostanie również wysłany na serwer, na którym zestaw SDK na platformie .NET Core zidentyfikuje go i użyje go do dowolnej telemetrii po stronie serwera, zgodnie z opisem w dokumentacji interfejsu API języka JavaScript.

W przypadku aplikacji JavaScript, które nie działają w taki sam sposób, jak ASP.NET Core MVC, takich jak aplikacje internetowe SPA, nadal trzeba będzie dodać appInsights.setAuthenticatedUserContext ręcznie.

Filtrowanie, wyszukiwanie i segmentowanie danych przy użyciu właściwości

Właściwości i miary można dołączać do zdarzeń, metryk, widoków stron, wyjątków i innych danych telemetrycznych.

Właściwości to wartości ciągów, których można użyć do filtrowania danych telemetrycznych w raportach użycia. Jeśli na przykład aplikacja udostępnia kilka gier, możesz dołączyć nazwę gry do każdego zdarzenia, aby zobaczyć, które gry są bardziej popularne.

Istnieje limit 8192 długości ciągu. Jeśli chcesz wysłać duże fragmenty danych, użyj parametru komunikatu .TrackTrace

Metryki to wartości liczbowe, które można przedstawiać graficznie. Na przykład możesz sprawdzić, czy istnieje stopniowy wzrost wyników osiąganych przez graczy. Wykresy można podzielić na segmenty według właściwości wysyłanych za pomocą zdarzenia, aby można było uzyskać oddzielne lub skumulowane wykresy dla różnych gier.

Wartości metryk powinny być większe lub równe 0, aby wyświetlić poprawnie.

Istnieją pewne ograniczenia dotyczące liczby właściwości, wartości właściwości i metryk , których można użyć.

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

Uwaga

Upewnij się, że nie rejestrujesz danych osobowych we właściwościach.

Alternatywny sposób ustawiania właściwości i metryk

Jeśli jest to wygodniejsze, możesz zebrać parametry zdarzenia w osobnym obiekcie:

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

Ostrzeżenie

Nie używaj tego samego wystąpienia elementu telemetrii (event w tym przykładzie) do wielokrotnego wywoływania Track*() . Ta praktyka może spowodować wysłanie danych telemetrycznych z nieprawidłową konfiguracją.

Niestandardowe pomiary i właściwości w usłudze Log Analytics

W usłudze Log Analytics metryki niestandardowe i właściwości są wyświetlane w customMeasurements atrybutach i customDimensions dla każdego rekordu telemetrii.

Jeśli na przykład dodasz właściwość o nazwie "game" do danych telemetrycznych żądania, to zapytanie zlicza wystąpienia różnych wartości "gry" i pokazuje średnią niestandardowej metryki "score":

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

Zwróć uwagę, że:

  • Po wyodrębnieniu wartości z pliku customDimensions lub customMeasurements JSON ma typ dynamiczny, dlatego należy go tostring rzutować lub todouble.
  • Aby uwzględnić możliwość próbkowania, użyj polecenia sum(itemCount) nie count().

Zdarzenia chronometrażu

Czasami chcesz utworzyć wykres czasu potrzebny do wykonania akcji. Możesz na przykład wiedzieć, jak długo użytkownicy będą rozważać wybory w grze. Aby uzyskać te informacje, użyj parametru pomiaru.

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

Domyślne właściwości niestandardowej telemetrii

Jeśli chcesz ustawić domyślne wartości właściwości dla niektórych zdarzeń niestandardowych, które zapisujesz, ustaw je w wystąpieniu TelemetryClient . Są one dołączone do każdego elementu telemetrii wysyłanego z tego 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"});

Poszczególne wywołania telemetryczne mogą zastąpić wartości domyślne w słownikach właściwości.

W przypadku klientów internetowych języka JavaScript użyj inicjatorów telemetrii Języka JavaScript.

Aby dodać właściwości do wszystkich danych telemetrycznych, w tym dane ze standardowych modułów kolekcji, zaimplementuj element ITelemetryInitializer.

Przykład, filtrowanie i przetwarzanie danych telemetrycznych

Kod do przetwarzania danych telemetrycznych można napisać przed wysłaniem go z zestawu SDK. Przetwarzanie obejmuje dane wysyłane z standardowych modułów telemetrycznych, takich jak zbieranie żądań HTTP i zbieranie zależności.

Dodaj właściwości do telemetrii, implementując element ITelemetryInitializer. Można na przykład dodać numery wersji lub wartości, które są obliczane z innych właściwości.

Filtrowanie może modyfikować lub odrzucać dane telemetryczne przed wysłaniem ich z zestawu SDK przez zaimplementowanie elementu ITelemetryProcessor. Możesz kontrolować, co zostało wysłane lub odrzucone, ale musisz uwzględnić wpływ na metryki. W zależności od sposobu odrzucania elementów możesz utracić możliwość nawigowania między powiązanymi elementami.

Próbkowanie to spakowane rozwiązanie w celu zmniejszenia ilości danych wysyłanych z aplikacji do portalu. Nie wpływa to na wyświetlane metryki. Nie ma to wpływu na możliwość diagnozowania problemów, przechodząc między powiązanymi elementami, takimi jak wyjątki, żądania i widoki stron.

Aby dowiedzieć się więcej, zobacz Filtrowanie i wstępne przetwarzanie danych telemetrycznych w zestawie SDK usługi Application Insights.

Wyłączanie telemetrii

Aby dynamicznie zatrzymać i uruchomić zbieranie i przesyłanie danych telemetrycznych:

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Aby wyłączyć wybrane standardowe moduły zbierające, na przykład liczniki wydajności, żądania HTTP lub zależności, usuń lub oznacz odpowiednie wiersze jako komentarz w ApplicationInsights.config. Przykładem jest wysłanie własnych TrackRequest danych.

Node.js

telemetry.config.disableAppInsights = true;

Aby wyłączyć wybrane standardowe moduły zbierające, na przykład liczniki wydajności, żądania HTTP lub zależności, w czasie inicjowania metody konfiguracji łańcucha do kodu inicjowania zestawu SDK.

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

Aby wyłączyć te moduły zbierające po zainicjowaniu, użyj obiektu Configuration: applicationInsights.Configuration.setAutoCollectRequests(false).

Tryb dewelopera

Podczas debugowania przydatne jest, aby dane telemetryczne zostały przyspieszone przez potok, dzięki czemu wyniki będą widoczne natychmiast. Otrzymujesz również inne komunikaty, które ułatwiają śledzenie problemów z telemetrią. Wyłącz ją w środowisku produkcyjnym, ponieważ może spowolnić działanie aplikacji.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

W przypadku Node.js możesz włączyć tryb dewelopera, włączając rejestrowanie wewnętrzne za pośrednictwem setInternalLogging i ustawienie na maxBatchSize0wartość , co powoduje wysłanie danych telemetrycznych zaraz po zebraniu.

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

Ustawianie klucza instrumentacji dla wybranej niestandardowej telemetrii

C#

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

Klucz instrumentacji dynamicznej

Aby uniknąć mieszania danych telemetrycznych z środowisk programistycznych, testowych i produkcyjnych, możesz utworzyć oddzielne zasoby usługi Application Insights i zmienić ich klucze w zależności od środowiska.

Zamiast uzyskiwać klucz instrumentacji z pliku konfiguracji, możesz ustawić go w kodzie. Ustaw klucz w metodzie inicjowania, na przykład global.aspx.cs w usłudze ASP.NET:

C#

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

JavaScript

appInsights.config.instrumentationKey = myKey;

Na stronach internetowych możesz ustawić go ze stanu serwera internetowego, a nie kodować go dosłownie do skryptu. Na przykład na stronie internetowej wygenerowanej w aplikacji ASP.NET:

JavaScript w środowisku Razor

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...
    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

TelemetryClient ma właściwość Context, która zawiera wartości wysyłane wraz ze wszystkimi danymi telemetrii. Są one zwykle ustawiane przez standardowe moduły telemetryczne, ale można je również ustawić samodzielnie. Przykład:

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

Jeśli ustawisz dowolną z tych wartości samodzielnie, rozważ usunięcie odpowiedniego wiersza z ApplicationInsights.config , aby wartości i wartości standardowe nie były mylone.

  • Składnik: aplikacja i jej wersja.
  • Urządzenie: dane dotyczące urządzenia, na którym działa aplikacja. W aplikacjach internetowych jest to serwer lub urządzenie klienckie, z którego są wysyłane dane telemetryczne.
  • InstrumentationKey: zasób usługi Application Insights na platformie Azure, na którym jest wyświetlana telemetria. Zazwyczaj jest to odebrane z ApplicationInsights.config.
  • Lokalizacja: lokalizacja geograficzna urządzenia.
  • Operacja: w aplikacjach internetowych bieżące żądanie HTTP. W innych typach aplikacji można ustawić tę wartość na grupowanie zdarzeń.
    • ID: wygenerowana wartość, która koreluje różne zdarzenia, dzięki czemu podczas inspekcji dowolnego zdarzenia w wyszukiwaniu diagnostycznym można znaleźć powiązane elementy.
    • Nazwa: identyfikator, zazwyczaj adres URL żądania HTTP.
    • Syntetyczne źródło: jeśli nie ma wartości null lub jest pusty, ciąg wskazujący, że źródło żądania zostało zidentyfikowane jako robot lub test internetowy. Domyślnie jest on wykluczony z obliczeń w Eksploratorze metryk.
  • Sesja: sesja użytkownika. Identyfikator jest ustawiony na wygenerowaną wartość, która jest zmieniana, gdy użytkownik nie był aktywny przez jakiś czas.
  • Użytkownik: informacje o użytkowniku.

Limity

Istnieją pewne limity dotyczące liczby metryk i zdarzeń na aplikację, czyli na klucz instrumentacji. Ograniczenia zależą od wybranego planu cenowego.

Zasób Limit domyślny Limit maksymalny Uwagi
Łączna ilość danych na dzień 100 GB Skontaktuj się z pomocą techniczną. Ilość danych możesz zmniejszyć, ustawiając limit. Jeśli potrzebujesz więcej danych, możesz zwiększyć limit w portalu do 1000 GB. W przypadku pojemności większych niż 1000 GB wyślij wiadomość e-mail na AIDataCap@microsoft.comadres .
Ograniczanie przepływności 32 000 zdarzeń na sekundę Skontaktuj się z pomocą techniczną. Limit jest mierzony przez minutę.
Dzienniki przechowywania danych Od 30 do 730 dni 730 dni Ten zasób jest przeznaczony dla dzienników.
Metryki przechowywania danych 90 dni 90 dni Ten zasób jest przeznaczony dla Eksploratora metryk.
Przechowywanie szczegółowych wyników testu wieloetapowego dostępności 90 dni 90 dni Ten zasób zapewnia szczegółowe wyniki każdego kroku.
Maksymalny rozmiar elementu telemetrii 64 KB 64 KB
Maksymalna liczba elementów telemetrii na partię 64,000 64,000
Długość nazwy właściwości i metryki 150 150 Zobacz schematy typów.
Długość ciągu wartości właściwości 8192 8192 Zobacz schematy typów.
Długość komunikatu śledzenia i wyjątku 32,768 32,768 Zobacz schematy typów.
Liczba testów dostępności na aplikację 100 100
Przechowywanie danych profilera i migawek Dwa tygodnie Skontaktuj się z pomocą techniczną. Maksymalny limit przechowywania wynosi sześć miesięcy.
Dane profilera wysyłane dziennie Bez ograniczeń Bez ograniczeń
Dane migawek wysyłane dziennie 30 migawek dziennie na monitorowaną aplikację Bez ograniczeń Liczbę migawek zebranych na aplikację można modyfikować za pomocą konfiguracji.

Aby uzyskać więcej informacji na temat cen i przydziałów, zobacz Rozliczenia usługi Application Insights.

Aby uniknąć osiągnięcia limitu szybkości danych, użyj próbkowania.

Aby określić, jak długo są przechowywane dane, zobacz Przechowywanie danych i prywatność.

Dokumenty referencyjne

Kod zestawu SDK

Często zadawane pytania

Dlaczego brakuje danych telemetrycznych?

Obie telemetriiChannels utracą buforowane dane telemetryczne, jeśli nie zostaną opróżnione przed zamknięciem aplikacji.

Aby uniknąć utraty danych, opróżnij obiekt TelemetryClient po zamknięciu aplikacji.

Aby uzyskać więcej informacji, zobacz Opróżnianie danych.

Jakie wyjątki mogą zgłaszać wywołania Track_() ?

Brak. Nie musisz opakowować ich w klauzulach try-catch. Jeśli zestaw SDK napotka problemy, będzie rejestrować komunikaty w danych wyjściowych konsoli debugowania i, jeśli komunikaty będą przekazywane, w wyszukiwaniu diagnostycznym.

Czy istnieje interfejs API REST do pobierania danych z portalu?

Tak, interfejs API dostępu do danych. Inne sposoby wyodrębniania danych obejmują usługę Power BI , jeśli przeprowadzono migrację do zasobu opartego na obszarze roboczym lub eksportu ciągłego , jeśli nadal korzystasz z zasobu klasycznego.

Dlaczego moje wywołania do niestandardowych zdarzeń i interfejsów API metryk są ignorowane?

Zestaw SDK usługi Application Insights nie jest zgodny z instrumentacją automatyczną. Jeśli jest włączona automatyczna instrumentacja, wywołania i Track() inne niestandardowe zdarzenia i interfejsy API metryk zostaną zignorowane.

Wyłącz automatyczne instrumentację w Azure Portal na karcie Application Insights na stronie App Service lub ustaw wartość ApplicationInsightsAgent_EXTENSION_VERSIONdisabled.

Następne kroki