Kanály telemetrie v Přehledy aplikací

  • Článek

Kanály telemetrie jsou nedílnou součástí sad SDK Přehledy aplikací. Spravují ukládání do vyrovnávací paměti a přenos telemetrie do služby Application Přehledy. Verze sad .NET a .NET Core sad SDK mají dva integrované kanály telemetrie: InMemoryChannel a ServerTelemetryChannel. Tento článek popisuje jednotlivé kanály a ukazuje, jak přizpůsobit chování kanálu.

Poznámka:

Následující dokumentace se spoléhá na rozhraní API Přehledy Application Přehledy Classic. Dlouhodobým plánem pro application Přehledy je shromažďovat data pomocí OpenTelemetry. Další informace najdete v tématu Povolení OpenTelemetry služby Azure Monitor pro aplikace .NET, Node.js, Python a Java.

Co jsou kanály telemetrie?

Kanály telemetrie zodpovídají za ukládání položek telemetrie do vyrovnávací paměti a jejich odesílání do služby Application Přehledy, kde jsou uložené pro dotazování a analýzu. Kanál telemetrie je libovolná třída, která implementuje Microsoft.ApplicationInsights.ITelemetryChannel rozhraní.

Metoda Send(ITelemetry item) kanálu telemetrie se volá po zavolání všech inicializátorů telemetrie a procesorů telemetrie. Všechny položky vyřazené procesorem telemetrie se proto nedostanou do kanálu. Metoda Send() obvykle neodesílá položky do back-endu okamžitě. Obvykle je ukládá do vyrovnávací paměti a odesílá je do dávek pro efektivní přenos.

Live Metrics Stream má také vlastní kanál, který využívá živé streamování telemetrie. Tento kanál je nezávislý na běžném kanálu telemetrie a tento dokument se na něj nevztahuje.

Integrované kanály telemetrie

Sady APPLICATION Přehledy .NET a .NET Core SDK se dodávají se dvěma integrovanými kanály:

  • InMemoryChannel: Jednoduchý kanál, který do vyrovnávací paměti ukládat položky do paměti, dokud se neposílají. Položky se ukládají do vyrovnávací paměti a vyprázdní se jednou za 30 sekund nebo každých 500 položek do vyrovnávací paměti. Tento kanál nabízí minimální záruky spolehlivosti, protože se po selhání nebude opakovat odesílání telemetrie. Tento kanál také neuchová položky na disku. Všechny neodehrané položky se proto při vypnutí aplikace trvale ztratí bez ohledu na to, jestli jsou elegantní, nebo ne. Tento kanál implementuje metodu Flush() , která se dá použít k synchronnímu vyprázdnění všech položek telemetrie v paměti. Tento kanál je vhodný pro krátkodobé aplikace, kde je ideální synchronní vyprázdnění.

    Tento kanál je součástí většího balíčku Microsoft.Application Přehledy NuGet a je výchozím kanálem, který sada SDK používá, když není nakonfigurováno nic jiného.

  • ServerTelemetryChannel: Pokročilejší kanál, který má zásady opakování a schopnost ukládat data na místní disk. Tento kanál opakuje odesílání telemetrie, pokud dojde k přechodným chybám. Tento kanál také používá místní diskové úložiště k uchovávání položek na disku během výpadků sítě nebo velkých svazků telemetrie. Vzhledem k těmto mechanismům opakování a úložišti místních disků se tento kanál považuje za spolehlivější. Doporučujeme ho pro všechny produkční scénáře. Tento kanál je výchozí pro aplikace ASP.NET a ASP.NET Core nakonfigurované podle oficiální dokumentace. Tento kanál je optimalizovaný pro scénáře serveru s dlouhotrvajícími procesy. Metoda Flush() implementovaná tímto kanálem není synchronní.

    Tento kanál se dodává jako Microsoft.Application Přehledy. Balíček NuGet WindowsServer.TelemetryChannel a získá se automaticky při použití microsoft.Application Přehledy. Web nebo Microsoft.Application Přehledy. Balíček NuGet AspNetCore

Konfigurace kanálu telemetrie

Kanál telemetrie nakonfigurujete tak, že ho nastavíte na aktivní konfiguraci telemetrie. Pro ASP.NET aplikace zahrnuje konfigurace nastavení instance kanálu telemetrie nebo TelemetryConfiguration.Active úpravou ApplicationInsights.config. U aplikací ASP.NET Core zahrnuje konfigurace přidání kanálu do kontejneru injektáž závislostí.

Následující části ukazují příklady konfigurace StorageFolder nastavení kanálu v různých typech aplikací. StorageFolder je pouze jedním z konfigurovatelných nastavení. Úplný seznam nastavení konfigurace najdete v části Konfigurovatelná nastavení v části Kanály dále v tomto článku.

Konfigurace pomocí application Přehledy.config pro aplikace ASP.NET

Následující část z aplikace Přehledy.config ukazuje ServerTelemetryChannel kanál nakonfigurovaný s nastaveným StorageFolder na vlastní umístění:

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

Konfigurace v kódu pro aplikace ASP.NET

Následující kód nastaví ServerTelemetryChannel instanci s StorageFolder nastavenou na vlastní umístění. Přidejte tento kód na začátek aplikace, obvykle v Application_Start() metodě v 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;
}

Konfigurace v kódu pro aplikace ASP.NET Core

ConfigureServices Upravte metodu Startup.cs třídy, jak je znázorněno zde:

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

Důležité

Konfigurace kanálu pomocí není TelemetryConfiguration.Active pro aplikace ASP.NET Core podporovaná.

Konfigurace v kódu pro konzolové aplikace .NET/.NET Core

Pro konzolové aplikace je kód stejný pro .NET i .NET Core:

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

Provozní podrobnosti o Nástroji ServerTelemetryChannel

ServerTelemetryChannel ukládá příchozí položky do vyrovnávací paměti. Položky jsou serializovány, komprimovány a uloženy do Transmission instance jednou za 30 sekund nebo při uložení 500 položek do vyrovnávací paměti. Jedna Transmission instance obsahuje až 500 položek a představuje dávku telemetrie, která se odesílá přes jedno volání HTTPS službě Application Přehledy.

Ve výchozím nastavení je možné paralelně odesílat maximálně 10 Transmission instancí. Pokud telemetrie přichází rychleji nebo pokud je síť nebo aplikace Přehledy back-end pomalý, Transmission instance se ukládají do paměti. Výchozí kapacita této vyrovnávací paměti v paměti Transmission je 5 MB. Po překročení Transmission kapacity v paměti se instance ukládají na místní disk až do limitu 50 MB.

Transmission Instance jsou uloženy na místním disku také v případě, že dochází k problémům se sítí. Pouze ty položky, které jsou uložené na místním disku, přežijí chybové ukončení aplikace. Posílají se pokaždé, když se aplikace znovu spustí. Pokud problémy se sítí potrvají, ServerTelemetryChannel použije se před opakovaným pokusem o odeslání telemetrie exponenciální logika zpětného od 10 sekund do 1 hodiny.

Konfigurovatelná nastavení v kanálech

Úplný seznam konfigurovatelných nastavení pro každý kanál najdete tady:

Tady jsou nejčastěji používaná nastavení pro ServerTelemetryChannel:

  • MaxTransmissionBufferCapacity: Maximální velikost paměti v bajtech, kterou kanál používá k ukládání přenosů do vyrovnávací paměti. Po dosažení této kapacity se nové položky ukládají přímo na místní disk. Výchozí hodnota je 5 MB. Nastavení vyšší hodnoty vede k menšímu využití disku, ale mějte na paměti, že pokud dojde k chybě aplikace, dojde ke ztrátě položek v paměti.
  • MaxTransmissionSenderCapacity: Maximální počet Transmission instancí, které budou odeslány do aplikace Přehledy současně. Výchozí hodnota je 10. Toto nastavení je možné nakonfigurovat na vyšší číslo, které doporučujeme, když se vygeneruje velký objem telemetrie. K vysokému objemu obvykle dochází během zátěžového testování nebo při vypnutí vzorkování.
  • StorageFolder: Složka, kterou kanál používá k ukládání položek na disk podle potřeby. Ve Windows se používá %LOCALAPPDATA% nebo %TEMP%, pokud není explicitně zadána žádná jiná cesta. V jiných prostředích než Windows musíte zadat platné umístění nebo telemetrii se neuloží na místní disk.

Jaký kanál mám použít?

Doporučujeme ServerTelemetryChannel pro většinu produkčních scénářů, které zahrnují dlouhotrvající aplikace. Metoda Flush() implementovaná ServerTelemetryChannel není synchronní. Nezaručuje také odesílání všech nevyřízených položek z paměti nebo disku.

Pokud tento kanál používáte ve scénářích, kdy se aplikace chystá vypnout, zaveď nějakou prodlevu po volání Flush(). Přesné množství zpoždění, které může vyžadovat, není předvídatelné. Závisí na faktorech, jako je počet položek nebo Transmission instancí v paměti, kolik je na disku, kolik se přenáší do back-endu a jestli je kanál uprostřed exponenciálních back-off scénářů.

Pokud potřebujete provést synchronní vyprázdnění, použijte InMemoryChannel.

Nejčastější dotazy

Tato část obsahuje odpovědi na běžné otázky.

Zaručuje kanál Application Insights doručování telemetrie? Pokud ne, jaké jsou scénáře, ve kterých může dojít ke ztrátě telemetrie?

Stručná odpověď je, že žádný z předdefinovaných kanálů nenabízí záruku doručení telemetrie do back-endu typu transakce. ServerTelemetryChannel je pokročilejší v porovnání se spolehlivým InMemoryChannel doručováním, ale zároveň se snaží odesílat telemetrii jen s nejlepším úsilím. Telemetrie může být stále ztracena v několika situacích, včetně těchto běžných scénářů:

  • Při chybovém ukončení aplikace dojde ke ztrátě položek v paměti.
  • Telemetrie se ztratí během delších období problémů se sítí. Telemetrie se ukládá na místní disk během výpadků sítě nebo v případě problémů s back-endem aplikace Přehledy. Položky starší než 48 hodin se však zahodí.
  • Výchozí umístění disků pro ukládání telemetrie ve Windows jsou %LOCALAPPDATA% nebo %TEMP%. Tato umístění jsou obvykle místní pro počítač. Pokud aplikace migruje fyzicky z jednoho umístění do jiného, dojde ke ztrátě všech telemetrických dat uložených v původním umístění.
  • Ve Službě Azure Web Apps ve Windows je výchozím umístěním úložiště disku D:\local\LocalAppData. Toto umístění není trvalé. Vymaže se v restartech aplikace, horizontálním navýšení kapacity a dalších takových operacích, což vede ke ztrátě jakékoli telemetrie uložené v ní. Výchozí nastavení můžete přepsat a zadat úložiště do trvalého umístění, jako je D:\home. Taková trvalá umístění však obsluhují vzdálené úložiště, takže může být pomalé.

I když je méně pravděpodobné, je také možné, že kanál může způsobit duplicitní položky telemetrie. K tomuto chování dochází při ServerTelemetryChannel opakování kvůli selhání sítě nebo vypršení časového limitu, kdy se telemetrie doručovala do back-endu, ale odezva se ztratila kvůli problémům se sítí nebo došlo k vypršení časového limitu.

Funguje ServerTelemetryChannel na jiných systémech než Windows?

I když název balíčku a oboru názvů zahrnuje "WindowsServer", tento kanál je podporován v jiných systémech než Windows, s následující výjimkou. V jiných systémech než Windows kanál ve výchozím nastavení nevytvoří složku místního úložiště. Musíte vytvořit složku místního úložiště a nakonfigurovat kanál tak, aby ho používal. Po nakonfigurování místního úložiště funguje kanál ve všech systémech stejným způsobem.

Poznámka:

S verzí 2.15.0-beta3 a novější se teď pro Linux, Mac a Windows automaticky vytvoří místní úložiště. V systémech, které nejsou systémy Windows, sada SDK automaticky vytvoří místní složku úložiště na základě následující logiky:

  • ${TMPDIR}: Pokud ${TMPDIR} je proměnná prostředí nastavená, použije se toto umístění.
  • /var/tmp: Pokud předchozí umístění neexistuje, zkusíme /var/tmpto .
  • /tmp: Pokud obě předchozí umístění neexistují, zkusíme tmpto .
  • Pokud žádná z těchto umístění neexistuje, místní úložiště se nevytvořilo a vyžaduje se ruční konfigurace. Úplné podrobnosti o implementaci najdete v tomto úložišti GitHubu.

Vytváří sada SDK dočasné místní úložiště? Jsou data zašifrovaná v úložišti?

Sada SDK ukládá položky telemetrie v místním úložišti během problémů se sítí nebo během omezování. Tato data nejsou místně šifrovaná.

V systémech Windows sada SDK automaticky vytvoří dočasnou místní složku v adresáři %TEMP% nebo %LOCALAPPDATA% a omezí přístup pouze správcům a aktuálnímu uživateli.

V případě systémů jiných než Windows se sada SDK automaticky nevytvořila žádná místní úložiště, takže žádná data se ve výchozím nastavení neukládají místně.

Poznámka:

S verzí 2.15.0-beta3 a novější se teď pro Linux, Mac a Windows automaticky vytvoří místní úložiště.

Adresář úložiště můžete vytvořit sami a nakonfigurovat kanál tak, aby ho používal. V tomto případě zodpovídáte za zajištění zabezpečení adresáře. Přečtěte si další informace o ochraně dat a ochraně osobních údajů.

Opensourcová sada SDK

Stejně jako každá sada SDK pro Přehledy aplikací jsou kanály open source. Přečtěte si kód a nahlašte problémy v oficiálním úložišti GitHubu.

Další kroky