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 aby ułatwić diagnozowanie problemów. Dane telemetryczne można wysyłać z aplikacji mobilnych i klasycznych, klientów internetowych i serwerów internetowych. Interfejs API podstawowej telemetrii usługi Azure Application Szczegółowe informacje umożliwia wysyłanie niestandardowych zdarzeń i metryk oraz własnych wersji standardowej telemetrii. Ten interfejs API jest tym samym interfejsem API, który jest Szczegółowe informacje modułów zbierających dane.

Podsumowanie interfejsu API

Podstawowy interfejs API jest jednolity na wszystkich platformach, z wyjątkiem kilku odmian, takich jak GetMetric (tylko .NET).

Metoda Sposób użycia
TrackPageView Strony, ekrany, blade lub formularze.
TrackEvent Akcje użytkownika i inne zdarzenia. Służy do śledzenia zachowania użytkowników lub monitorowania wydajności.
GetMetric Metryki zero i wielowymiarowe, centralnie skonfigurowana agregacja, tylko język C#.
TrackMetric Miary wydajności, takie jak długość kolejki, które nie są powiązane z określonymi zdarzeniami.
TrackException Rejestrowanie wyjątków diagnostyki. Śledzenie miejsca ich wystąpienia w odniesieniu do innych zdarzeń i badanie śladów stosu.
TrackRequest Rejestrowanie częstotliwości i czasu trwania żądań serwera w celu analizy wydajności.
TrackTrace Komunikaty dziennika diagnostycznego zasobu. Można 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ń telemetrii 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 Szczegółowe informacje:

Uzyskiwanie wystąpienia TelemetryClient

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

W ASP.NET Core aplikacji i aplikacji innych niż HTTP/Worker dla aplikacji .NET/.NET Core zaleca się pobrać wystąpienie z kontenera wstrzykiwania zależności, jak wyjaśniono w odpowiedniej TelemetryClient dokumentacji.

Jeśli używasz funkcji AzureFunctions w wersji 2 lub Azure WebJobs w wersji 3+ — postępuj zgodnie z tym dokumentem.

C#

private TelemetryClient telemetry = new TelemetryClient();

Aby uzyskać szczegółowe informacje dla wszystkich osób, które widzą tę metodę, są przestarzałe, odwiedź stronę 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 jest bezpieczny wątkowo.

W ASP.NET i java przychodzące żądania HTTP są przechwytywane automatycznie. Możesz utworzyć dodatkowe wystąpienia klasy TelemetryClient dla innego modułu aplikacji. Na przykład w klasie oprogramowania pośredniczącego może być jedno wystąpienie TelemetryClient do zgłaszania 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ń, które wysyła wystąpienie.

C#

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

Java

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

W Node.js można użyć do utworzenia nowego wystąpienia, ale jest to zalecane tylko w przypadku scenariuszy, które wymagają izolowanej konfiguracji od new applicationInsights.TelemetryClient(instrumentationKey?) pojedynczego wystąpienia defaultClient .

TrackEvent

W programie Application Szczegółowe informacje zdarzenie niestandardowe jest punktem danych, który można wyświetlić w programie Eksplorator metryk jako zagregowana liczba, a w wyszukiwaniu diagnostycznym jako pojedyncze wystąpienia. (Nie jest on powiązany ze "zdarzeniami" MVC ani inną platformą).

Wstaw TrackEvent wywołania w kodzie, aby zliczyć różne zdarzenia. Jak często użytkownicy wybierają określoną funkcję, jak często osiągają konkretne cele lub jak często popełniają konkretne 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 analizie

Telemetria jest dostępna w tabeli na karcie Dzienniki Szczegółowe informacje aplikacji lub customEvents w obszarze Środowisko użytkowania. Zdarzenia mogą pochodzić z trackEvent(..) lub kliknąć wtyczkę automatycznego zbierania danych analizy.

Jeśli próbkowanie jest w działaniu, właściwość itemCount pokazuje wartość większą niż 1. Na przykład itemCount==10 oznacza, że z 10 wywołań metody trackEvent() proces próbkowania przesłał tylko jedno z nich. Aby uzyskać poprawną liczbę zdarzeń niestandardowych, należy w związku z tym użyć kodu takiego jak customEvents | summarize sum(itemCount) .

GetMetric

Aby dowiedzieć się, jak skutecznie używać wywołania GetMetric() do przechwytywania lokalnie wstępnie zagregowanych metryk dla aplikacji .NET i .NET Core, zapoznaj się z dokumentacją funkcji GetMetric.

TrackMetric

Uwaga

Metoda Microsoft.ApplicationInsights.TelemetryClient.TrackMetric nie jest preferowaną metodą wysyłania metryk. Metryki należy zawsze wstępnie agregować w okresie przed ich wysłaniem. Użyj jednego z przeciążeń metody GetMetric(..), aby uzyskać obiekt metryki w celu uzyskania dostępu do możliwości wstępnej agregacji zestawu SDK. Jeśli implementujesz własną logikę wstępnej agregacji, możesz użyć metody TrackMetric(), aby wysłać wynikowe agregacje. Jeśli aplikacja wymaga wysyłania oddzielnego elementu telemetrii przy każdej okazji bez agregacji w czasie, prawdopodobnie masz przypadek użycia dla telemetrii zdarzeń; zobacz TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Metryki Szczegółowe informacje mogą być wykresami, 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 pomiary mają mniejsze zainteresowanie niż wariacje i trendy, dlatego wykresy statystyczne są przydatne.

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

  • Pojedyncza wartość. Za każdym razem, gdy wykonujesz miarę w aplikacji, wysyłasz odpowiednią wartość do aplikacji Application Szczegółowe informacje. Załóżmy na przykład, że masz metrykę opisująca liczbę elementów w kontenerze. W określonym okresie należy najpierw umieścić trzy elementy w kontenerze, a następnie usunąć dwa elementy. W związku z tym należy wywołać wywołanie TrackMetric dwa razy: najpierw przekazując wartość, 3 a następnie wartość -2 . Aplikacja Szczegółowe informacje przechowuje obie wartości w Twoim imieniu.

  • Agregacja. Podczas pracy z metrykami każdy pojedynczy pomiar rzadko się interesuje. Zamiast tego ważne jest podsumowanie tego, co się stało w określonym okresie. Takie podsumowanie jest nazywane agregacją. W powyższym przykładzie zagregowana suma metryk dla tego okresu wynosi , a 1 liczba wartości metryk to 2 . W przypadku korzystania z metody agregacji można wywoływać tylko raz w każdym TrackMetric okresie i wysyłać wartości zagregowane. Jest to zalecane podejście, ponieważ może znacznie zmniejszyć koszty i wydajność, wysyłając mniejszą liczbę punktów danych do aplikacji Szczegółowe informacje, jednocześnie zbierając wszystkie istotne informacje.

Przykłady

Pojedyncze wartości

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

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

C#

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Value = 42.3;
telemetryClient.TrackMetric(sample);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

telemetry.trackMetric({name: "queueLength", value: 42.0});

Metryki niestandardowe w analizie

Dane telemetryczne są dostępne w tabeli customMetrics usługi Application Szczegółowe informacje Analytics. Każdy wiersz reprezentuje wywołanie w trackMetric(..) aplikacji.

  • valueSum — Jest to suma pomiarów. Aby uzyskać wartość średnią, podziel przez valueCount .
  • valueCount — liczba pomiarów, które zostały zagregowane w tym trackMetric(..) wywołaniu.

Wyświetlenia stron

W aplikacji urządzenia lub strony internetowej telemetria widoku strony jest wysyłana domyślnie po załadowaniu każdego ekranu lub strony. Można to jednak zmienić, aby śledzić wyświetlenia stron o dodatkowych lub różnych godzinach. Na przykład w aplikacji, która wyświetla karty lub bloku, możesz chcieć śledzić stronę za każdym razem, gdy użytkownik otworzy nowy blok.

Dane użytkownika i sesji są wysyłane jako właściwości wraz z widokami stron, dzięki czemu wykresy użytkownika i sesji są aktywne, gdy istnieje telemetria widoku strony.

Niestandardowe wyświetlenia 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, gdy przeglądarka wyśle żądanie, aż do momentu wywoływania zdarzenia ładowania strony przeglądarki.

Zamiast tego możesz:

  • Ustaw jawny czas trwania w wywołaniu trackPageView: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds); .
  • Użyj wywołań chronometrażu widoku strony startTrackPage 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, która jest określana jako pierwszy parametr, kojarzy wywołania uruchamiania i zatrzymania. Domyślnie jest to nazwa bieżącej strony.

Wynikowe czasy trwania ładowania strony wyświetlane w Eksplorator metryk są uzyskiwane na podstawie interwału między wywołaniami uruchamiania i zatrzymania. To Od Ciebie jest to, jaki interwał faktycznie ma być czas.

Telemetria stron w analizie

W analizie dwie tabele pokazują dane z operacji przeglądarki:

  • Tabela pageViews zawiera dane dotyczące adresu URL i tytułu strony
  • Tabela zawiera dane dotyczące wydajności klienta, takie jak czas browserTimings przetwarzania danych przychodzących

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

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

Aby poznać popularne przeglądarki:

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 logowania żądań HTTP.

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

Jednak zalecanym sposobem wysyłania telemetrii żądania jest miejsce, w którym żądanie działa jako kontekst operacji.

Kontekst operacji

Elementy telemetrii można skojarzyć ze sobą, kojarząc je z kontekstem operacji. Standardowy moduł śledzenia żądań robi to dla wyjątków i innych zdarzeń, które są wysyłane podczas przetwarzania żądania HTTP. W usługach Search and Analyticsmożna łatwo znaleźć wszystkie zdarzenia skojarzone z żądaniem przy użyciu jego identyfikatora operacji.

Zobacz Korelacja telemetrii w Szczegółowe informacje, aby uzyskać więcej informacji na temat korelacji.

W przypadku ręcznego śledzenia telemetrii najprostszym sposobem zapewnienia korelacji telemetrii przy użyciu 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 operacji StartOperation program tworzy element telemetrii o typie, który określisz. Element telemetrii jest wysyłany podczas usuwania operacji lub w przypadku jawnego StopOperation wywołania . Jeśli używasz typu telemetrii, jego czas trwania jest ustawiony na interwał czasu między uruchomieniem RequestTelemetry i zatrzymaniem.

Elementy telemetrii zgłoszone w zakresie operacji stają się elementami "elementami" tej operacji. Konteksty operacji mogą być zagnieżdżone.

W polu Wyszukaj kontekst operacji służy do tworzenia listy Powiązane elementy:

Elementy pokrewne

Aby uzyskać więcej informacji na temat śledzenia operacji niestandardowych, zobacz Track custom operations with Application Szczegółowe informacje .NET SDK (Śledzenie operacji niestandardowych za pomocą zestawu SDK platformy .NET usługi Application).

Żądania w analizie

W u Szczegółowe informacje Analyticsżądania są wyświetlane w requests tabeli.

Jeśli próbkowanie jest w działaniu, właściwość itemCount będzie pokazywać wartość większą niż 1. Na przykład itemCount==10 oznacza, że z 10 wywołań metody trackRequest() proces próbkowania przesłał tylko jedno z nich. Aby uzyskać poprawną liczbę żądań i średni czas trwania segmentacji 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 aplikacji Szczegółowe informacje:

Raporty zawierają ś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 jawnie wywołać wyjątek TrackException.

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

Wyjątki w analizie

W aplikacji Application Szczegółowe informacje Analyticswyjątki są wyświetlane w exceptions tabeli.

Jeśli próbkowanie jest w działaniu, itemCount właściwość pokazuje wartość większą niż 1. Na przykład itemCount==10 oznacza, że z 10 wywołań metody trackException() proces próbkowania przesłał tylko jedno z nich. Aby uzyskać poprawną 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żesz rozdzielić details strukturę, aby uzyskać więcej. Ponieważ ta struktura jest dynamiczna, należy rzutować wynik na typ, jakiego oczekujesz. 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

Śledzenie śledzenia

Użyj funkcji TrackTrace, aby ułatwić diagnozowanie problemów, wysyłając "ścieżkę nakierową" do aplikacji Szczegółowe informacje. Możesz wysyłać fragmenty danych diagnostycznych i sprawdzać je w wyszukiwaniu diagnostycznym.

Karty dziennika platformy .NET używają tego interfejsu API do wysyłania dzienników innych firm do portalu.

W języku Java agent Szczegółowe informacje automatycznie zbiera 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
});

Kod JavaScript po stronie klienta/przeglądarki

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

Rejestrowanie zdarzenia diagnostycznego, takiego jak wprowadzenie metody lub opuszczenie metody.

Parametr Opis
message Dane diagnostyczne. Może być znacznie dłuższy niż nazwa.
properties Mapowanie ciągu na ciąg: dodatkowe dane używane do filtrowania wyjątków w portalu. Wartość domyślna to empty (puste).
severityLevel Obsługiwane wartości: SeverityLevel.ts

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

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

Ponadto do komunikatu można dodać poziom ważności. Podobnie jak w przypadku innych telemetrii, 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 poluWyszukaj można następnie łatwo odfiltrować wszystkie komunikaty o określonym poziomie ważności, które odnoszą się do określonej bazy danych.

Ślady w analizie

W u Szczegółowe informacje Analyticswywołania funkcji TrackTrace są wyświetlane w traces tabeli.

Jeśli próbkowanie jest w działaniu, właściwość itemCount pokazuje wartość większą niż 1. Na przykład itemCount ==10 oznacza, że z 10 wywołań do trackTrace() metody proces próbkowania przesłał tylko jedno z nich. Aby uzyskać poprawną liczbę wywołań śledzenia, należy użyć kodu takiego jak traces | summarize sum(itemCount) .

TrackDependency (Zależność śledzenia)

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 należy dodać wszędzie tam, gdzie jest wykonane wywołanie zależności.

Uwaga

W przypadku platform .NET i .NET Core możesz też użyć metody (extension), która wypełnia właściwości wymagane do korelacji i innych właściwości, takich jak czas rozpoczęcia i czas trwania, dzięki czemu nie trzeba tworzyć niestandardowego czasomierza, jak w poniższych TelemetryClient.StartOperation DependencyTelemetry przykładach. Aby uzyskać więcej informacji, zapoznaj się z sekcją tego artykułu na temat śledzenia zależności wychodzących.

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 automatycznie odnajduje i śledzi niektóre wywołania zależności — 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 usługi Application Szczegółowe informacje Java.

Tego wywołania należy użyć, jeśli chcesz śledzić wywołania, których zautomatyzowane śledzenie nie przechwytuje.

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

Zależności w analizie

W u Szczegółowe informacje Analyticsw tabeli są wyświetlane wywołania trackDependency. dependencies

Jeśli próbkowanie jest w działaniu, właściwość itemCount pokazuje wartość większą niż 1. Na przykład itemCount==10 oznacza, że z 10 wywołań metody trackDependency() proces próbkowania przesłał tylko jedno 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 ustalonych odstępach czasu (zazwyczaj 30 s) lub zawsze, gdy bufor jest pełny (zazwyczaj 500 elementów). Jednak w niektórych przypadkach może być konieczne opróżnienie buforu — na przykład w przypadku używania zestawu SDK w aplikacji, która zostanie zamknięta.

C#

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

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.

Idealnym rozwiązaniem jest zastosowanie metody flush() w działaniu zamykania aplikacji.

Uwierzytelnieni użytkownicy

W aplikacji internetowej użytkownicy są (domyślnie) identyfikowani przez pliki cookie. Użytkownik może być liczony więcej niż raz, jeśli uzyskuje dostęp do aplikacji z innego komputera lub przeglądarki albo jeśli usuwa pliki cookie.

Jeśli użytkownicy logują się do twojej aplikacji, możesz uzyskać bardziej dokładną liczbę, ustawiając identyfikator uwierzytelnionego 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);
    ...
}

W aplikacji internetowej ASP.NET MVC, na przykład:

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 unikatowy dla tego użytkownika. Nie może zawierać spacji ani żadnego ze znaków ,;=| .

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

Jeśli aplikacja grupuje użytkowników na konta, możesz również przekazać identyfikator konta (z tym samymi ograniczeniami znaków).

appInsights.setAuthenticatedUserContext(validatedId, accountId);

W Eksplorator metrykmożna utworzyć wykres, który zlicza konta użytkowników, uwierzytelnionych i 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 klasy zestaw .NET Core SDK upraszcza konfigurację języka JavaScript potrzebną do wstrzykania nazwy użytkownika jako identyfikatora uwierzytelniania dla każdego śledzenia wysyłanego przez zestaw SDK języka JavaScript usługi Application Szczegółowe informacje. Gdy ta właściwość jest ustawiona na wartość true, nazwa użytkownika z usługi ASP.NET Core jest drukowana wraz z telemetrią po stronie klienta,więc ręczne dodawanie nie będzie już potrzebne, ponieważ jest już wstrzykiwane przez zestaw SDK dla appInsights.setAuthenticatedUserContext ASP.NET Core. Identyfikator uwierzytelniania zostanie również wysłany do serwera, na którym zestaw SDK na platformie .NET Core zidentyfikuje go i użyje go do obsługi dowolnych danych telemetrycznych po stronie serwera, zgodnie z opisem w odwołaniach interfejsu API języka JavaScript. Jednak 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 należy 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ń (a także do metryk, wyświetleń 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 telemetrii w raportach użycia. Jeśli na przykład twoja 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 wysyłać duże fragmenty danych, użyj parametru komunikatu TrackTrace).

Metryki to wartości liczbowe, które mogą być prezentowane graficznie. Możesz na przykład sprawdzić, czy istnieje stopniowy wzrost wyników osiąganych przez twój łasuch. Wykresy mogą być segmentowane według właściwości wysyłanych wraz ze zdarzeniem, dzięki czemu można uzyskać oddzielne lub skumulowane wykresy dla różnych gier.

Aby wartości metryk były prawidłowo wyświetlane, powinny być większe niż lub równe 0.

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

Należy zadbać o to, aby nie rejestrować danych osobowych we właściwościach.

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

Jeśli jest to wygodniejsze, możesz zebrać parametry zdarzenia w oddzielnym 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 ponownie tego samego wystąpienia elementu telemetrii (w tym przykładzie) do wielokrotnego wywołania event elementu Track*(). Może to spowodować, że dane telemetryczne będą wysyłane z nieprawidłową konfiguracją.

Niestandardowe miary i właściwości w analizie

W analizieniestandardowe metryki i właściwości są wyświetlane w customMeasurements atrybutach i customDimensions każdego rekordu telemetrii.

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

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

Zwróć uwagę, że:

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

Zdarzenia chronometrażu

Czasami chcesz pokazać, jak długo trwa wykonywanie akcji. Możesz na przykład chcieć wiedzieć, jak długo użytkownicy rozważają wybory w grze. W tym celu możesz użyć parametru miary.

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 telemetrii niestandardowej

Jeśli chcesz ustawić domyślne wartości właściwości dla niektórych niestandardowych zdarzeń, które piszesz, możesz ustawić je w wystąpieniu TelemetryClient. Są one dołączane 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 telemetrii mogą przesłonić wartości domyślne w swoich słownikach właściwości.

W przypadku klientów internetowych w języku 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, zaim implementuj . ITelemetryInitializer

Próbkowanie, filtrowanie i przetwarzanie danych telemetrycznych

Możesz napisać kod do przetwarzania danych telemetrycznych przed ich wysłaniem z zestawu SDK. Przetwarzanie obejmuje dane wysyłane ze standardowych modułów telemetrii, takich jak zbieranie żądań HTTP i zbieranie zależności.

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

Filtrowanie może modyfikować lub odrzucać dane telemetryczne przed ich wysłaniem z zestawu SDK przez zaimplementowanie . ITelemetryProcessor Możesz kontrolować, co jest wysyłane lub odrzucane, 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, które pozwala zmniejszyć ilość danych wysyłanych z aplikacji do portalu. Robi to bez wpływu na wyświetlane metryki. Odbywa się to bez wpływu na zdolność diagnozowania problemów przez nawigowanie między powiązanymi elementami, takimi jak wyjątki, żądania i wyświetlenia stron.

Dowiedz się więcej.

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ł zbierające— na przykład liczniki wydajności, żądania HTTP lub zależności — usuń lub zakłoń odpowiednie wiersze wApplicationInsights.config. Możesz to zrobić, na przykład jeśli chcesz wysłać własne dane TrackRequest.

Node.js

telemetry.config.disableAppInsights = true;

Aby wyłączyć wybrane standardowe moduł zbierające — na przykład liczniki wydajności, żądania HTTP lub zależności — w czasie inicjowania należy przyłączyć łańcuch metod konfiguracji do kodu inicjalizacji zestawu SDK:

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

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

Tryb dewelopera

Podczas debugowania warto przyspieszyć telemetrię w potoku, aby natychmiast zobaczyć wyniki. Otrzymasz również dodatkowe komunikaty, które ułatwiają śledzenie wszelkich problemów z telemetrią. Wyłącz ją w środowisku produkcyjnym, ponieważ może to spowolnić aplikację.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Na Node.js można włączyć tryb dewelopera, włączając rejestrowanie wewnętrzne za pośrednictwem funkcji i ustawiając na 0, co powoduje, że dane telemetryczne są wysyłane natychmiast po setInternalLogging maxBatchSize 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ąć łączenia danych telemetrycznych ze środowisk deweloperskich, testowych i produkcyjnych, można utworzyć oddzielne zasoby usługi Application Szczegółowe informacje i zmienić ich klucze w zależności od środowiska.

Zamiast uzyskać klucz instrumentacji z pliku konfiguracji, możesz ustawić go w kodzie. Ustaw klucz w metodzie inicjowania, takiej jak global.aspx.cs, w ASP.NET service:

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

Język JavaScript w języku 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

Obiekt TelemetryClient ma właściwość Context, która zawiera wartości wysyłane wraz ze wszystkimi danymi telemetrycznymi. Zwykle są one ustawiane przez standardowe moduły telemetrii, 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 zApplicationInsights.config , aby nie mylić wartości i wartości standardowych.

  • Składnik: aplikacja i jej wersja.
  • Urządzenie: dane dotyczące urządzenia, na którym jest uruchomiona aplikacja. (W aplikacjach internetowych jest to serwer lub urządzenie klienckie, z których są wysyłane dane telemetryczne).
  • InstrumentationKey: zasób Application Szczegółowe informacje na platformie Azure, w którym jest wyświetlana telemetria. Zazwyczaj jest on wybierany z ApplicationInsights.config.
  • Lokalizacja: lokalizacja geograficzna urządzenia.
  • Operacja: w aplikacjach internetowych bieżące żądanie HTTP. W przypadku innych typów aplikacji możesz ustawić tę wartość tak, aby zdarzenia grupować ze sobą.
    • Identyfikator: wygenerowana wartość, która skoreluje 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.
    • SyntheticSource: jeśli nie ma wartości null lub jest pusta, ciąg wskazujący, że źródło żądania zostało zidentyfikowane jako test robota lub testu sieci Web. Domyślnie jest ona wykluczona z obliczeń w Eksplorator metryk.
  • Sesja: sesja użytkownika. Identyfikator jest ustawiany 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 ograniczenia dotyczące liczby metryk i zdarzeń dla aplikacji, czyli według klucza Instrumentacji. Ograniczenia zależą od wybranego planu cenowego.

Zasób Limit domyślny Uwaga
Łączna ilość danych na dzień 100 GB Ilość danych możesz zmniejszyć, ustawiając limit. Jeśli potrzebujesz więcej danych, możesz zwiększyć limit w portalu, do 1 000 GB. W przypadku pojemności większej niż 1 000 GB Wyślij wiadomość e-mail na adres AIDataCap@microsoft.com .
Ograniczanie przepływności 32 000 zdarzeń/sekundę Limit jest mierzony przez minutę.
Dzienniki przechowywania danych 30-730 dni Ten zasób jest przeznaczony dla dzienników.
Metryki przechowywania danych 90 dni Ten zasób jest przeznaczony dla Eksplorator metryk.
Przechowywanie szczegółowych wyników wieloetapowego testu dostępności 90 dni Ten zasób zapewnia szczegółowe wyniki każdego kroku.
Maksymalny rozmiar elementu telemetrii 64 kB
Maksymalna liczba elementów telemetrii na partię 64 K
Długość nazwy właściwości i metryki 150 Zobacz schematy typów.
Długość ciągu wartości właściwości 8192 Zobacz schematy typów.
Długość komunikatu śledzenia i wyjątku 32 768 Zobacz schematy typów.
Liczba testów dostępności na aplikację 100
Przechowywanie danych profilera 5 dni
Dane profilera wysłane dziennie 10 GB

Aby uzyskać informacje, zobacz Informacje o zarządzaniu cenami i limitami przydziału dla usługi Application Insights.

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

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

Dokumenty referencyjne

Kod zestawu SDK

Pytania

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

    Brak. Nie trzeba opaowywanie ich w klauzule try-catch. Jeśli zestaw SDK napotka problemy, będzie rejestrować komunikaty w danych wyjściowych konsoli debugowania i — jeśli komunikaty zostaną za pośrednictwem — w wyszukiwaniu diagnostycznym.

  • Czy istnieje interfejs API REST do odbierania danych z portalu?

    Tak, interfejs API dostępu do danych. Inne sposoby wyodrębniania danych obejmują eksport z analizy do Power BI eksport ciągły.

Następne kroki