Udostępnij za pośrednictwem

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

  • Artykuł

Wstaw kilka wierszy kodu w aplikacji, aby dowiedzieć się, co użytkownicy robią z nim, lub aby ułatwić diagnozowanie problemów. Dane telemetryczne można wysyłać z aplikacji urządzeń i komputerów stacjonarnych, 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ą standardowe 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 parametry połączenia w celu skorzystania z nowych funkcji.

Podsumowanie interfejsu API

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

Method 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ść kolejki, niezwiązane z określonymi zdarzeniami.
TrackException Rejestrowanie wyjątków dla diagnostyki. Śledź, gdzie występują w odniesieniu do innych zdarzeń i zbadaj ślady 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.

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

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 platformy .NET/.NET Core pobierz wystąpienie TelemetryClient z kontenera wstrzykiwania zależności, zgodnie z opisem w odpowiedniej dokumentacji.

Jeśli używasz usługi Azure Functions w wersji 2 lub nowszej lub usługi Azure WebJobs w wersji 3 lub nowszej, zobacz Monitorowanie usługi 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 w klasie oprogramowania pośredniczącego w celu raportowania zdarzeń logiki biznesowej. Możesz ustawić właściwości, takie jak UserId i DeviceId , aby 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ć nowe wystąpienie za pomocą new applicationInsights.TelemetryClient(instrumentationKey?) polecenia . Zalecamy to podejście tylko w przypadku scenariuszy, które wymagają izolowanej konfiguracji od 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 inną strukturą "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ż chcieć 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 kolekcji analizy kliknięć.

Jeśli próbkowanie jest wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład oznacza, itemCount==10 że z 10 wywołań do trackEvent()metody , 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

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

GetMetric

Aby dowiedzieć się, jak skutecznie używać GetMetric() wywołania do przechwytywania metryek wstępnie zagregowanych lokalnie dla aplikacji .NET i .NET Core, zobacz Zbieranie metryk niestandardowych na platformach .NET i .NET Core.

TrackMetric

Uwaga

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

Jeśli wdrażasz własną logikę przed agregacją, 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 istnieje przypadek użycia telemetrii zdarzeń. Zobacz: TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Usługa Application Insights może wyświetlać 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ż różnice i trendy, dlatego wykresy statystyczne są przydatne.

Aby wysył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ę opisjącą 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 należy zadzwonić TrackMetric dwa razy. 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 pojedyncza miara jest rzadko interesująca. Zamiast tego ważne jest podsumowanie tego, co wydarzyło się w określonym okresie. Takie podsumowanie jest nazywane agregacją.

    W poprzednim przykładzie suma zagregowanej metryki dla tego okresu to 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ć zagregowane wartości. Zalecamy takie podejście, ponieważ może znacznie zmniejszyć koszty i obciążenie związane z wydajnością, 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 customMetrics tabeli w usłudze Application Insights Analytics. Każdy wiersz reprezentuje wywołanie metody trackMetric(..) w aplikacji.

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

Uwaga

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

Widoki stron

W aplikacji urządzenia lub strony internetowej dane telemetryczne widoku strony są wysyłane domyślnie po załadowaniu każdego ekranu lub strony. Można jednak zmienić wartość domyślną, aby śledzić wyświetlenia stron w więcej lub innym czasie. 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");

Wyświetlenia 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żesz wykonać następujące czynności:

  • Ustaw jawny czas trwania w wywołaniu 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. Domyślnie jest używana 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 czas.

Telemetria stron 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, połącz się z zależnościami:

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 sytuacja, w której żą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źć wszelkie zdarzenia skojarzone z żądaniem przy użyciu jego identyfikatora operacji.

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

Podczas 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 w przypadku jawnego wywołania metody StopOperation. Jeśli używasz RequestTelemetry jako typu telemetrii, jego czas trwania jest ustawiony na interwał czasowy 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ę Elementy pokrewne.

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 wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład oznacza, itemCount==10 że z 10 wywołań do trackRequest()metody , proces próbkowania przesłany tylko jeden z nich. Aby uzyskać prawidłową liczbę żądań i średni czas trwania segmentowany 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 wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład oznacza, itemCount==10 że z 10 wywołań do trackException()metody , proces próbkowania przesłany tylko jeden z nich. Aby uzyskać prawidłową liczbę wyjątków segmentowanych 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żna ściągnąć details strukturę, aby uzyskać więcej. Ponieważ ta struktura jest dynamiczna, należy rzutować wynik na oczekiwany typ. Na 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

Służy TrackTrace do diagnozowania problemów przez wysłanie "szlaku 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 java usługi Application Insights autokolektuje 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
});

Język JavaScript po stronie klienta/przeglądarki

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

Rejestrowanie zdarzenia diagnostycznego, takiego jak wprowadzanie lub opuszczanie metody.

Parametr Opis
message Dane diagnostyczne. Może być znacznie dłuższa niż nazwa.
properties Mapa ciągu 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 jej 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. Możesz na przykład zakodować tam dane POST.

Możesz również dodać poziom ważności do wiadomości. Podobnie jak inne dane telemetryczne, możesz dodać wartości właściwości, aby ułatwić filtrowanie lub wyszukiwanie różnych zestawów śladów. Na 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 mają TrackTrace być wyświetlane w traces tabeli.

Jeśli próbkowanie jest wykonywane, itemCount właściwość pokazuje wartość większą niż 1. Na przykład oznacza, itemCount==10 że z 10 wywołań do trackTrace()metody , 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

Użyj wywołania , TrackDependency 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 musi zostać dodany wszędzie tam, gdzie jest wykonywane wywołanie zależności.

Uwaga

W przypadku platform .NET i .NET Core można również użyć TelemetryClient.StartOperation metody (rozszerzenia), która wypełnia DependencyTelemetry właściwości potrzebne do korelacji i niektórych innych właściwości, takich jak czas rozpoczęcia i czas trwania, więc nie trzeba 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
    });
}

Należy pamiętać, ż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 moduł działał, 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 plik ApplicationInsights.config i usuń odwołanie do DependencyCollector.DependencyTrackingTelemetryModule. Aby zapoznać się z językiem Java, zobacz Pomijanie określonych automatycznie generowanych 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, itemCount==10 że z 10 wywołań do trackDependency()metody , proces próbkowania przesłany tylko jeden z nich. Aby uzyskać poprawną liczbę zależności segmentowanych 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óżniany po zamknięciu aplikacji.
  • Przejrzyj konfigurację automatycznego napływu: włączenie automatycznego napływu w web.config pliku może prowadzić do obniżenia wydajności w aplikacjach platformy .NET instrumentowanych za pomocą usługi Application Insights. Po włączeniu funkcji automatycznego napływu System.Diagnostics.Trace.Trace* każde wywołanie metod powoduje wysłanie poszczególnych elementów telemetrii jako oddzielnych odrębnych żądań internetowych do usługi pozyskiwania. Może to potencjalnie spowodować wyczerpanie sieci i magazynu na serwerach internetowych. Aby zwiększyć wydajność, zaleca się wyłączenie automatycznego napływu, a także korzystanie z serverTelemetryChannel, przeznaczonego do bardziej efektywnej transmisji danych telemetrycznych.

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 jest konieczne użycie rzeczywistej nazwy logowania użytkownika. Musi być tylko identyfikatorem unikatowym 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 zarówno telemetrii klienta, jak 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 wstrzykiwania nazwy użytkownika jako identyfikatora uwierzytelniania dla każdego śledzenia wysyłanego przez zestaw SDK języka JavaScript usługi Application Insights.

Gdy ta właściwość jest ustawiona na true, nazwa użytkownika od użytkownika w ASP.NET Core jest drukowana wraz z telemetrią po stronie klienta. Z tego powodu dodanie appInsights.setAuthenticatedUserContext ręcznie nie będzie już potrzebne, ponieważ jest już wstrzykiwane przez zestaw SDK dla platformy 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 dla 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 appInsights.setAuthenticatedUserContext dodać 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 wydarzenia, aby zobaczyć, które gry są bardziej popularne.

Długość ciągu wynosi 8192. 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 występuje stopniowy wzrost wyników osiąganych przez graczy. Wykresy można podzielić na segmenty według właściwości, które są wysyłane ze zdarzeniem, aby można było uzyskać oddzielne lub skumulowane grafy dla różnych gier.

Wartości metryki 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*() . Takie rozwiązanie 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 wyświetla średnią metryki niestandardowej "score":

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

Zwróć uwagę, że:

  • Podczas wyodrębniania wartości z customDimensions pliku lub customMeasurements JSON ma typ dynamiczny, dlatego należy go tostring rzutować lub todouble.
  • Aby wziąć pod uwagę możliwość próbkowania, należy użyć nie count().sum(itemCount)

Zdarzenia chronometrażu

Czasami chcesz utworzyć wykres czasu potrzebnego do wykonania akcji. Na przykład możesz chcieć 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 zapisywanych zdarzeń niestandardowych, 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 danych ze standardowych modułów kolekcji, zaimplementuj element ITelemetryInitializer.

Przykład, filtrowanie i przetwarzanie danych telemetrycznych

Zobacz Filtrowanie i wstępne przetwarzanie danych telemetrycznych w zestawie SDK usługi Application Insights.

Wyłączanie telemetrii

Aby dynamicznie zatrzymywać i uruchamiać 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 jako komentarz odpowiednie wiersze w elemencie 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 przyspieszenie telemetrii za pośrednictwem potoku, dzięki czemu wyniki będą widoczne natychmiast. Otrzymujesz również inne komunikaty, które ułatwiają śledzenie wszelkich 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 funkcji setInternalLogging i ustawienie maxBatchSize na 0, co powoduje wysyłanie danych telemetrycznych natychmiast po zebraniu.

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

Ustawianie klucza instrumentacji dla wybranej telemetrii niestandardowej

C#

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

Klucz instrumentacji dynamicznej

Aby uniknąć mieszania danych telemetrycznych ze ś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 zamiast 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);
    }

TelemetriaContext

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

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

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

  • 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 pobierane 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, aby 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 liczby metryk i zdarzeń na aplikację, czyli na klucz instrumentacji. Ograniczenia zależą od wybranego planu cenowego.

Zasób Limit domyślny Maksymalny limit Uwagi
Łączna ilość danych na dzień 100 GB Skontaktuj się z pomocą techniczną. Możesz ustawić limit w celu zmniejszenia ilości danych. 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 8,192 8,192 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 zasób usługi Application Insights 100 100
Liczba testów dostępności na grupę zasobów 800 800 Zobacz Azure Resource Manager
Maksymalna liczba przekierowań na test testów dostępności 10 10
Minimalna częstotliwość testów dostępności 300 sekund Niestandardowe częstotliwości testów lub częstotliwości krótsze niż 5 minut wymagają niestandardowych implementacji TrackAvailability .
Przechowywanie danych profilera i migawki Dwa tygodnie Skontaktuj się z pomocą techniczną. Maksymalny limit przechowywania wynosi sześć miesięcy.
Dane profilera wysyłane dziennie Brak ograniczeń Brak limitu.
Dane migawek wysyłane dziennie 30 migawek dziennie na monitorowaną aplikację Brak limitu. 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

Ta sekcja zawiera odpowiedzi na typowe pytania.

Dlaczego brakuje danych telemetrycznych?

Obie telemetriiChannel 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 opakowywać 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 są 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 autoinstrumentacją. Jeśli funkcja autoinstrumentacji jest włączona, wywołania Track() i inne niestandardowe zdarzenia i interfejsy API metryk zostaną zignorowane.

Wyłącz automatyczneinstrumentację w witrynie Azure Portal na karcie Application Insights na stronie usługi App Service lub ustaw wartość ApplicationInsightsAgent_EXTENSION_VERSION disabled.

Dlaczego liczby wykresów wyszukiwania i metryk są nierówne?

Próbkowanie zmniejsza liczbę elementów telemetrii (takich jak żądania i zdarzenia niestandardowe), które są wysyłane z aplikacji do portalu. W obszarze Wyszukaj zostanie wyświetlona liczba odebranych elementów. Na wykresach metryk, które wyświetlają liczbę zdarzeń, zobaczysz liczbę oryginalnych zdarzeń, które wystąpiły.

Każdy przesłany element zawiera itemCount właściwość, która pokazuje, ile oryginalnych zdarzeń reprezentuje dany element. Aby obserwować próbkowanie w operacji, możesz uruchomić to zapytanie w usłudze Log Analytics:

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

Jak mogę ustawić alert dotyczący zdarzenia?

Alerty platformy Azure dotyczą tylko metryk. Utwórz niestandardową metrykę, która przekracza próg wartości przy każdym wystąpieniu zdarzenia. Następnie ustaw alert dotyczący metryki. Otrzymasz powiadomienie za każdym razem, gdy metryka przekroczy próg w dowolnym kierunku. Nie otrzymasz powiadomienia do momentu pierwszego przejścia, bez względu na to, czy początkowa wartość jest wysoka, czy niska. Zawsze występuje opóźnienie kilku minut.

Następne kroki