Kanały telemetryczne w usłudze Application Szczegółowe informacje

  • Artykuł

Kanały telemetryczne są integralną częścią zestawów SDK usługi Application Szczegółowe informacje. Zarządzają buforowaniem i przesyłaniem danych telemetrycznych do usługi Application Szczegółowe informacje. Wersje zestawów SDK platformy .NET i .NET Core mają dwa wbudowane kanały telemetryczne: InMemoryChannel i ServerTelemetryChannel. W tym artykule opisano każdy kanał i pokazano, jak dostosować zachowanie kanału.

Uwaga

Poniższa dokumentacja opiera się na klasycznym interfejsie API usługi Application Szczegółowe informacje. Długoterminowy plan Szczegółowe informacje aplikacji polega na zbieraniu danych przy użyciu biblioteki OpenTelemetry. Aby uzyskać więcej informacji, zobacz Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications (Włączanie usługi Azure Monitor OpenTelemetry dla platformy .NET, Node.js, Python i Java applications).

Co to są kanały telemetryczne?

Kanały telemetryczne są odpowiedzialne za buforowanie elementów telemetrii i wysyłanie ich do usługi Application Szczegółowe informacje, gdzie są przechowywane na potrzeby wykonywania zapytań i analizy. Kanał telemetrii to dowolna klasa, która implementuje Microsoft.ApplicationInsights.ITelemetryChannel interfejs.

Metoda Send(ITelemetry item) kanału telemetrii jest wywoływana po wywołaniu wszystkich inicjatorów telemetrii i procesorów telemetrii. W związku z tym wszystkie elementy porzucone przez procesor telemetrii nie będą docierać do kanału. Metoda Send() zwykle nie wysyła elementów do zaplecza natychmiast. Zazwyczaj buforuje je w pamięci i wysyła je w partiach w celu wydajnego przesyłania.

Transmisja strumieniowa metryk na żywo ma również niestandardowy kanał obsługujący transmisję strumieniową na żywo danych telemetrycznych. Ten kanał jest niezależny od zwykłego kanału telemetrii, a ten dokument nie ma do niego zastosowania.

Wbudowane kanały telemetryczne

Zestawy SDK aplikacji Szczegółowe informacje .NET i .NET Core są dostarczane z dwoma wbudowanymi kanałami:

  • InMemoryChannel: lekki kanał, który buforuje elementy w pamięci do momentu ich wysłania. Elementy są buforowane w pamięci i opróżniane co 30 sekund lub za każdym razem, gdy buforowane są 500 elementów. Ten kanał oferuje minimalne gwarancje niezawodności, ponieważ nie ponawia próby wysyłania danych telemetrycznych po awarii. Ten kanał nie przechowuje również elementów na dysku. W związku z tym wszelkie niesprawne elementy zostaną trwale utracone po zamknięciu aplikacji, niezależnie od tego, czy jest to łaskawy, czy nie. Ten kanał implementuje metodę Flush() , która może służyć do wymuszania synchronicznego opróżniania wszystkich elementów telemetrycznych w pamięci. Ten kanał jest odpowiedni dla krótko działających aplikacji, w których idealne jest synchroniczne opróżnienie.

    Ten kanał jest częścią większego pakietu Microsoft.Application Szczegółowe informacje NuGet i jest domyślnym kanałem używanym przez zestaw SDK, gdy nic innego nie jest skonfigurowane.

  • ServerTelemetryChannel: Bardziej zaawansowany kanał, który ma zasady ponawiania prób i możliwość przechowywania danych na dysku lokalnym. Ten kanał ponawia próbę wysyłania danych telemetrycznych, jeśli wystąpią błędy przejściowe. Ten kanał używa również magazynu dysków lokalnych do przechowywania elementów na dysku podczas awarii sieci lub dużych woluminów telemetrycznych. Ze względu na te mechanizmy ponawiania prób i magazyn dysku lokalnego ten kanał jest uważany za bardziej niezawodny. Zalecamy to dla wszystkich scenariuszy produkcyjnych. Ten kanał jest domyślny dla aplikacji ASP.NET i ASP.NET Core skonfigurowanych zgodnie z oficjalną dokumentacją. Ten kanał jest zoptymalizowany pod kątem scenariuszy serwera z długotrwałymi procesami. Flush() Metoda zaimplementowana przez ten kanał nie jest synchroniczna.

    Ten kanał jest dostarczany jako Microsoft.Application Szczegółowe informacje. Pakiet NuGet WindowsServer.TelemetryChannel i jest uzyskiwany automatycznie podczas korzystania z pakietu Microsoft.Application Szczegółowe informacje. Web lub Microsoft.Application Szczegółowe informacje. Pakiet NuGet aspNetCore.

Konfigurowanie kanału telemetrii

Kanał telemetrii można skonfigurować, ustawiając go na aktywną konfigurację telemetrii. W przypadku aplikacji ASP.NET konfiguracja obejmuje ustawienie wystąpienia kanału telemetrii na TelemetryConfiguration.Active lub przez zmodyfikowanie elementu ApplicationInsights.config. W przypadku aplikacji ASP.NET Core konfiguracja obejmuje dodanie kanału do kontenera wstrzykiwania zależności.

W poniższych sekcjach przedstawiono przykłady konfigurowania StorageFolder ustawienia kanału w różnych typach aplikacji. StorageFolder jest tylko jednym z konfigurowalnych ustawień. Pełną listę ustawień konfiguracji można znaleźć w sekcji Konfigurowanie ustawień w kanałach w dalszej części tego artykułu.

Konfiguracja przy użyciu pliku Application Szczegółowe informacje.config dla aplikacji ASP.NET

W poniższej sekcji z sekcji Application Szczegółowe informacje.config przedstawiono ServerTelemetryChannel kanał skonfigurowany z StorageFolder ustawieniem lokalizacji niestandardowej:

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity  -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

Konfiguracja w kodzie dla aplikacji ASP.NET

Poniższy kod konfiguruje ServerTelemetryChannel wystąpienie z StorageFolder ustawioną lokalizacją niestandardową. Dodaj ten kod na początku aplikacji, zazwyczaj w metodzie Application_Start() w Global.aspx.cs.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
    serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

Konfiguracja w kodzie dla aplikacji ASP.NET Core

Zmodyfikuj metodę ConfigureServicesStartup.cs klasy, jak pokazano poniżej:

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

Ważne

Konfigurowanie kanału przy użyciu programu TelemetryConfiguration.Active nie jest obsługiwane w przypadku aplikacji ASP.NET Core.

Konfiguracja w kodzie dla aplikacji konsolowych .NET/.NET Core

W przypadku aplikacji konsolowych kod jest taki sam zarówno dla platformy .NET, jak i platformy .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Szczegóły operacyjne serverTelemetryChannel

ServerTelemetryChannel przechowuje przychodzące elementy w buforze w pamięci. Elementy są serializowane, skompresowane i przechowywane w wystąpieniu Transmission co 30 sekund lub gdy buforowane są 500 elementów. Pojedyncze Transmission wystąpienie zawiera maksymalnie 500 elementów i reprezentuje partię danych telemetrycznych wysyłanych za pośrednictwem jednego wywołania HTTPS do usługi Application Szczegółowe informacje.

Domyślnie można wysyłać równolegle maksymalnie 10 Transmission wystąpień. Jeśli dane telemetryczne docierają szybciej lub sieć lub zaplecze aplikacji Szczegółowe informacje działa wolno, Transmission wystąpienia są przechowywane w pamięci. Domyślna pojemność tego buforu w pamięci Transmission wynosi 5 MB. Po przekroczeniu Transmission pojemności w pamięci wystąpienia są przechowywane na dysku lokalnym do limitu 50 MB.

Transmission wystąpienia są przechowywane na dysku lokalnym również wtedy, gdy występują problemy z siecią. Tylko te elementy, które są przechowywane na dysku lokalnym, przetrwają awarię aplikacji. Są one wysyłane za każdym razem, gdy aplikacja zostanie uruchomiona ponownie. Jeśli problemy z siecią będą się powtarzać, ServerTelemetryChannel użyje logiki wycofywania wykładniczego z zakresu od 10 sekund do 1 godziny przed ponowieniem próby wysłania danych telemetrycznych.

Konfigurowalne ustawienia w kanałach

Aby uzyskać pełną listę konfigurowalnych ustawień dla każdego kanału, zobacz:

Poniżej przedstawiono najczęściej używane ustawienia dla programu ServerTelemetryChannel:

  • MaxTransmissionBufferCapacity: maksymalna ilość pamięci w bajtach używana przez kanał do buforowania transmisji w pamięci. Po osiągnięciu tej pojemności nowe elementy są przechowywane bezpośrednio na dysku lokalnym. Wartość domyślna to 5 MB. Ustawienie wyższej wartości prowadzi do mniejszego użycia dysku, ale pamiętaj, że elementy w pamięci zostaną utracone w przypadku awarii aplikacji.
  • MaxTransmissionSenderCapacity: maksymalna liczba Transmission wystąpień, które zostaną wysłane do aplikacji Szczegółowe informacje w tym samym czasie. Wartość domyślna to 10. To ustawienie można skonfigurować do większej liczby, która jest zalecana w przypadku wygenerowania ogromnej ilości danych telemetrycznych. Duża ilość zwykle występuje podczas testowania obciążenia lub gdy próbkowanie jest wyłączone.
  • StorageFolder: folder używany przez kanał do przechowywania elementów na dysku zgodnie z potrzebami. W systemie Windows używany jest %LOCALAPPDATA% lub %TEMP%, jeśli żadna inna ścieżka nie zostanie jawnie określona. W środowiskach innych niż Windows należy określić prawidłową lokalizację lub dane telemetryczne nie będą przechowywane na dysku lokalnym.

Którego kanału należy używać?

Zalecamy ServerTelemetryChannel korzystanie z większości scenariuszy produkcyjnych obejmujących długotrwałe aplikacje. Flush() Metoda zaimplementowana przez ServerTelemetryChannel program nie jest synchroniczna. Nie gwarantuje również wysyłania wszystkich oczekujących elementów z pamięci lub dysku.

Jeśli używasz tego kanału w scenariuszach, w których aplikacja ma zostać zamknięta, wprowadź pewne opóźnienie po wywołaniu metody Flush(). Dokładna ilość opóźnień, które mogą być wymagane, nie jest przewidywalna. Zależy to od czynników, takich jak liczba elementów lub Transmission wystąpień w pamięci, ile jest na dysku, ile jest przesyłanych do zaplecza i czy kanał znajduje się w środku scenariuszy wycofywania wykładniczego.

Jeśli musisz wykonać synchroniczne opróżnienie, użyj polecenia InMemoryChannel.

Często zadawane pytania

Ta sekcja zawiera odpowiedzi na typowe pytania.

Czy kanał usługi Application Insights gwarantuje dostarczanie danych telemetrycznych? Jeśli nie, jakie są scenariusze, w których można utracić dane telemetryczne?

Krótka odpowiedź polega na tym, że żaden z wbudowanych kanałów nie oferuje gwarancji typu transakcji dostarczania telemetrii do zaplecza. ServerTelemetryChannel jest bardziej zaawansowany w porównaniu z usługą InMemoryChannel w celu zapewnienia niezawodnego dostarczania, ale również sprawia, że tylko próba wysłania danych telemetrycznych jest najlepsza. Dane telemetryczne mogą być nadal tracone w kilku sytuacjach, w tym w następujących typowych scenariuszach:

  • Elementy w pamięci zostaną utracone, gdy aplikacja ulegnie awarii.
  • Dane telemetryczne są tracone w dłuższych okresach problemów z siecią. Dane telemetryczne są przechowywane na dysku lokalnym podczas awarii sieci lub gdy wystąpią problemy z zapleczem usługi Application Szczegółowe informacje. Jednak elementy starsze niż 48 godzin są odrzucane.
  • Domyślne lokalizacje dysków do przechowywania danych telemetrycznych w systemie Windows to %LOCALAPPDATA% lub %TEMP%. Te lokalizacje są zwykle lokalne dla maszyny. Jeśli aplikacja migruje fizycznie z jednej lokalizacji do innej, wszelkie dane telemetryczne przechowywane w oryginalnej lokalizacji zostaną utracone.
  • W usłudze Azure Web Apps w systemie Windows domyślna lokalizacja magazynu dysków to D:\local\LocalAppData. Ta lokalizacja nie jest utrwalone. Jest on wyczyszczony w przypadku ponownego uruchamiania aplikacji, skalowania w poziomie i innych takich operacji, co prowadzi do utraty przechowywanych tam danych telemetrycznych. Możesz zastąpić wartość domyślną i określić magazyn do utrwalonej lokalizacji, takiej jak D:\home. Jednak takie utrwalone lokalizacje są obsługiwane przez magazyn zdalny i dlatego mogą być powolne.

Chociaż mniej prawdopodobne, kanał może również spowodować zduplikowane elementy telemetrii. To zachowanie występuje, gdy ServerTelemetryChannel ponawianie prób z powodu awarii sieci lub przekroczenia limitu czasu, gdy telemetria została dostarczona do zaplecza, ale odpowiedź została utracona z powodu problemów z siecią lub wystąpiło przekroczenie limitu czasu.

Czy ServerTelemetryChannel działa w systemach innych niż Windows?

Mimo że nazwa pakietu i przestrzeni nazw zawiera ciąg "WindowsServer", ten kanał jest obsługiwany w systemach innych niż Windows, z następującym wyjątkiem. W systemach innych niż Windows kanał domyślnie nie tworzy lokalnego folderu magazynu. Musisz utworzyć folder magazynu lokalnego i skonfigurować kanał, aby go używał. Po skonfigurowaniu magazynu lokalnego kanał działa tak samo jak we wszystkich systemach.

Uwaga

W wersji 2.15.0-beta3 i nowszych magazyn lokalny jest teraz automatycznie tworzony dla systemów Linux, Mac i Windows. W przypadku systemów innych niż Windows zestaw SDK automatycznie utworzy lokalny folder magazynu na podstawie następującej logiki:

  • ${TMPDIR}: Jeśli zmienna środowiskowa jest ustawiona ${TMPDIR} , ta lokalizacja jest używana.
  • /var/tmp: Jeśli poprzednia lokalizacja nie istnieje, spróbujemy wykonać próbę /var/tmp.
  • /tmp: Jeśli obie poprzednie lokalizacje nie istnieją, spróbujemy użyć polecenia tmp.
  • Jeśli żadna z tych lokalizacji nie istnieje, magazyn lokalny nie zostanie utworzony, a konfiguracja ręczna będzie nadal wymagana. Aby uzyskać szczegółowe informacje o implementacji, zobacz to repozytorium GitHub.

Czy zestaw SDK tworzy magazyn lokalny tymczasowy? Czy dane są szyfrowane w magazynie?

Zestaw SDK przechowuje elementy telemetryczne w magazynie lokalnym podczas problemów z siecią lub podczas ograniczania przepustowości. Te dane nie są szyfrowane lokalnie.

W przypadku systemów Windows zestaw SDK automatycznie tworzy tymczasowy folder lokalny w katalogu %TEMP% lub %LOCALAPPDATA% i ogranicza dostęp tylko do administratorów i bieżącego użytkownika.

W przypadku systemów innych niż Windows żaden magazyn lokalny nie jest tworzony automatycznie przez zestaw SDK, więc żadne dane nie są przechowywane lokalnie.

Uwaga

W wersji 2.15.0-beta3 i nowszych magazyn lokalny jest teraz automatycznie tworzony dla systemów Linux, Mac i Windows.

Możesz samodzielnie utworzyć katalog magazynu i skonfigurować go do użycia. W takim przypadku odpowiadasz za zapewnienie, że katalog jest zabezpieczony. Przeczytaj więcej na temat ochrony danych i prywatności.

Zestaw SDK typu open source

Podobnie jak każdy zestaw SDK dla Szczegółowe informacje aplikacji, kanały są typu open source. Odczytywanie i współtworzenie kodu lub zgłaszanie problemów w oficjalnym repozytorium GitHub.

Następne kroki