Telemetriekanalen in Application Insights

  • Artikel

Telemetriekanalen vormen een integraal onderdeel van de Application Insights SDK's. Ze beheren buffering en overdracht van telemetrie naar de Application Insights-service. De .NET- en .NET Core-versies van de SDK's hebben twee ingebouwde telemetriekanalen: InMemoryChannel en ServerTelemetryChannel. In dit artikel wordt elk kanaal beschreven en wordt uitgelegd hoe u kanaalgedrag aanpast.

Notitie

De volgende documentatie is afhankelijk van de klassieke Application Insights-API. Het langetermijnplan voor Application Insights is het verzamelen van gegevens met behulp van OpenTelemetry. Zie Azure Monitor OpenTelemetry inschakelen voor .NET-, Node.js-, Python- en Java-toepassingen voor meer informatie.

Wat zijn telemetriekanalen?

Telemetriekanalen zijn verantwoordelijk voor het bufferen van telemetrie-items en het verzenden ervan naar de Application Insights-service, waar ze worden opgeslagen voor het uitvoeren van query's en analyses. Een telemetriekanaal is een klasse die de Microsoft.ApplicationInsights.ITelemetryChannel interface implementeert.

De Send(ITelemetry item) methode van een telemetriekanaal wordt aangeroepen nadat alle telemetrie-initialisatiefuncties en telemetrieprocessors worden aangeroepen. Alle items die door een telemetrieprocessor worden verwijderd, bereiken het kanaal dus niet. De Send() methode verzendt de items gewoonlijk niet onmiddellijk naar de back-end. Normaal gesproken buffert het ze in het geheugen en verzendt ze in batches voor efficiënte verzending.

Live Metrics Stream heeft ook een aangepast kanaal dat de livestreaming van telemetrie mogelijk maakt. Dit kanaal is onafhankelijk van het normale telemetriekanaal en dit document is niet van toepassing op het kanaal.

Ingebouwde telemetriekanalen

De .NET- en .NET Core SDK's van Application Insights worden geleverd met twee ingebouwde kanalen:

  • InMemoryChannel: Een lichtgewicht kanaal waarmee items in het geheugen worden gebufferd totdat ze worden verzonden. Items worden in het geheugen gebufferd en elke 30 seconden leeggemaakt, of wanneer 500 items worden gebufferd. Dit kanaal biedt minimale betrouwbaarheidsgaranties omdat het geen telemetrie opnieuw probeert te verzenden na een fout. Dit kanaal bewaart ook geen items op schijf. Alle niet-verzonden items gaan dus definitief verloren bij het afsluiten van de toepassing, ongeacht of deze correct zijn of niet. Dit kanaal implementeert een Flush() methode die kan worden gebruikt om eventuele in-memory telemetrie-items synchroon te wissen. Dit kanaal is zeer geschikt voor kortlopende toepassingen waarbij een synchrone flush ideaal is.

    Dit kanaal maakt deel uit van het grotere NuGet-pakket Microsoft.ApplicationInsights en is het standaardkanaal dat de SDK gebruikt wanneer er niets anders is geconfigureerd.

  • ServerTelemetryChannel: Een geavanceerder kanaal met beleid voor opnieuw proberen en de mogelijkheid om gegevens op een lokale schijf op te slaan. Dit kanaal probeert opnieuw telemetrie te verzenden als er tijdelijke fouten optreden. Dit kanaal maakt ook gebruik van lokale schijfopslag om items op schijf te houden tijdens netwerkstoringen of hoge telemetrievolumes. Vanwege deze mechanismen voor opnieuw proberen en lokale schijfopslag wordt dit kanaal beschouwd als betrouwbaarder. We raden dit aan voor alle productiescenario's. Dit kanaal is de standaardinstelling voor ASP.NET- en ASP.NET Core-toepassingen die zijn geconfigureerd volgens de officiële documentatie. Dit kanaal is geoptimaliseerd voor serverscenario's met langlopende processen. De Flush() methode die door dit kanaal wordt geïmplementeerd, is niet synchroon.

    Dit kanaal wordt geleverd als het NuGet-pakket Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel en wordt automatisch verkregen wanneer u het NuGet-pakket Microsoft.ApplicationInsights.Web of Microsoft.ApplicationInsights.AspNetCore gebruikt.

Een telemetriekanaal configureren

U configureert een telemetriekanaal door dit in te stellen op de actieve telemetrieconfiguratie. Voor ASP.NET toepassingen moet de configuratie het exemplaar van het telemetriekanaal TelemetryConfiguration.Active instellen op of door deze te ApplicationInsights.configwijzigen. Voor ASP.NET Core-toepassingen moet de configuratie het kanaal toevoegen aan de container voor afhankelijkheidsinjectie.

In de volgende secties ziet u voorbeelden van het configureren van de StorageFolder instelling voor het kanaal in verschillende toepassingstypen. StorageFolder is slechts een van de configureerbare instellingen. Zie de sectie Configureerbare instellingen in kanalen verderop in dit artikel voor de volledige lijst met configuratie-instellingen.

Configuratie met applicationInsights.config voor ASP.NET toepassingen

In de volgende sectie van ApplicationInsights.config ziet u het ServerTelemetryChannel kanaal dat is geconfigureerd met StorageFolder ingesteld op een aangepaste locatie:

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

Configuratie in code voor ASP.NET toepassingen

Met de volgende code wordt een ServerTelemetryChannel exemplaar ingesteld op StorageFolder een aangepaste locatie. Voeg deze code toe aan het begin van de toepassing, meestal in de Application_Start() methode in 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;
}

Configuratie in code voor ASP.NET Core-toepassingen

Wijzig de ConfigureServices methode van de Startup.cs klasse, zoals hier wordt weergegeven:

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

Belangrijk

Het configureren van het kanaal met behulp van TelemetryConfiguration.Active wordt niet ondersteund voor ASP.NET Core-toepassingen.

Configuratie in code voor .NET/.NET Core-consoletoepassingen

Voor console-apps is de code hetzelfde voor zowel .NET als .NET Core:

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

Operationele details van ServerTelemetryChannel

ServerTelemetryChannel slaat binnenkomende items op in een buffer in het geheugen. De items worden elke 30 seconden geserialiseerd, gecomprimeerd en opgeslagen in een Transmission exemplaar of wanneer er 500 items zijn gebufferd. Eén Transmission exemplaar bevat maximaal 500 items en vertegenwoordigt een batch telemetriegegevens die via één HTTPS-aanroep naar de Application Insights-service worden verzonden.

Standaard kunnen maximaal 10 Transmission exemplaren parallel worden verzonden. Als telemetrie sneller aankomt of als het netwerk of de Application Insights-back-end traag is, Transmission worden exemplaren opgeslagen in het geheugen. De standaardcapaciteit van deze in-memory Transmission buffer is 5 MB. Wanneer de capaciteit in het geheugen is overschreden, Transmission worden exemplaren op de lokale schijf opgeslagen tot een limiet van 50 MB.

Transmission exemplaren worden op de lokale schijf opgeslagen, ook wanneer er netwerkproblemen zijn. Alleen items die zijn opgeslagen op een lokale schijf, overleven een toepassingscrash. Ze worden verzonden wanneer de toepassing opnieuw wordt gestart. Als netwerkproblemen zich blijven voordoen, ServerTelemetryChannel gebruikt u een exponentieel uitstellogica van 10 seconden tot 1 uur voordat u opnieuw probeert telemetrie te verzenden.

Configureerbare instellingen in kanalen

Zie voor de volledige lijst met configureerbare instellingen voor elk kanaal:

Hier volgen de meestgebruikte instellingen voor ServerTelemetryChannel:

  • MaxTransmissionBufferCapacity: De maximale hoeveelheid geheugen, in bytes, die door het kanaal wordt gebruikt om transmissies in het geheugen te bufferen. Wanneer deze capaciteit is bereikt, worden nieuwe items rechtstreeks op de lokale schijf opgeslagen. De standaardwaarde is 5 MB. Het instellen van een hogere waarde leidt tot minder schijfgebruik, maar onthoud dat items in het geheugen verloren gaan als de toepassing vastloopt.
  • MaxTransmissionSenderCapacity: Het maximum aantal Transmission exemplaren dat tegelijkertijd naar Application Insights wordt verzonden. De standaardwaarde is 10. Deze instelling kan worden geconfigureerd voor een hoger getal, wat we aanbevelen wanneer een groot aantal telemetriegegevens wordt gegenereerd. Een hoog volume treedt meestal op tijdens het testen van de belasting of wanneer steekproeven zijn uitgeschakeld.
  • StorageFolder: De map die door het kanaal wordt gebruikt om items naar schijf op te slaan, indien nodig. In Windows wordt %LOCALAPPDATA% of %TEMP% gebruikt als er geen ander pad expliciet is opgegeven. In andere omgevingen dan Windows moet u een geldige locatie of telemetrie opgeven die niet op de lokale schijf wordt opgeslagen.

Welk kanaal moet ik gebruiken?

We raden u aan ServerTelemetryChannel voor de meeste productiescenario's waarbij langlopende toepassingen worden gebruikt. De Flush() methode die door ServerTelemetryChannel is geïmplementeerd, is niet synchroon. Het biedt ook geen garantie voor het verzenden van alle items die in behandeling zijn vanuit het geheugen of de schijf.

Als u dit kanaal gebruikt in scenario's waarin de toepassing op het punt staat af te sluiten, voert u enige vertraging in nadat u belt Flush(). De exacte hoeveelheid vertraging die u mogelijk nodig hebt, is niet voorspelbaar. Het is afhankelijk van factoren zoals hoeveel items of Transmission exemplaren zich in het geheugen bevinden, hoeveel er op de schijf staan, hoeveel worden er naar de back-end verzonden en of het kanaal zich midden in exponentieel back-offscenario's bevindt.

Als u een synchrone opspoeling wilt uitvoeren, gebruikt u InMemoryChannel.

Veelgestelde vragen

In deze sectie vindt u antwoorden op veelgestelde vragen.

Garandeert het Application Insights-kanaal de levering van telemetrie? Zo niet, wat zijn de scenario's waarin telemetrie verloren kan gaan?

Het korte antwoord is dat geen van de ingebouwde kanalen een transactietypegarantie biedt voor telemetrielevering aan de back-end. ServerTelemetryChannel is geavanceerder vergeleken met InMemoryChannel betrouwbare levering, maar het maakt ook slechts een best-effort poging om telemetrie te verzenden. Telemetrie kan nog steeds verloren gaan in verschillende situaties, waaronder deze veelvoorkomende scenario's:

  • Items in het geheugen gaan verloren wanneer de toepassing vastloopt.
  • Telemetrie gaat verloren tijdens langere perioden van netwerkproblemen. Telemetrie wordt opgeslagen op de lokale schijf tijdens netwerkstoringen of wanneer er problemen optreden met de Application Insights-back-end. Items ouder dan 48 uur worden echter verwijderd.
  • De standaardschijflocaties voor het opslaan van telemetrie in Windows zijn %LOCALAPPDATA% of %TEMP%. Deze locaties zijn doorgaans lokaal op de computer. Als de toepassing fysiek van de ene locatie naar de andere wordt gemigreerd, gaan alle telemetriegegevens die zijn opgeslagen op de oorspronkelijke locatie verloren.
  • In Azure Web Apps in Windows is de standaardlocatie voor schijfopslag D:\local\LocalAppData. Deze locatie blijft niet behouden. Het wordt gewist bij het opnieuw opstarten van apps, uitschalen en andere dergelijke bewerkingen, wat leidt tot verlies van telemetrie die daar is opgeslagen. U kunt de standaardinstelling overschrijven en opslag opgeven op een permanente locatie zoals D:\home. Dergelijke permanente locaties worden echter geleverd door externe opslag en kunnen dus traag zijn.

Hoewel het minder waarschijnlijk is, is het ook mogelijk dat het kanaal dubbele telemetrie-items kan veroorzaken. Dit gedrag treedt op bij ServerTelemetryChannel nieuwe pogingen vanwege netwerkfouten of time-outs, wanneer de telemetrie aan de back-end werd geleverd, maar het antwoord is verloren gegaan vanwege netwerkproblemen of er is een time-out opgetreden.

Werkt ServerTelemetryChannel op andere systemen dan Windows?

Hoewel de naam van het pakket en de naamruimte 'WindowsServer' bevat, wordt dit kanaal ondersteund op andere systemen dan Windows, met de volgende uitzondering. Op andere systemen dan Windows maakt het kanaal standaard geen lokale opslagmap. U moet een lokale opslagmap maken en het kanaal configureren voor gebruik. Nadat de lokale opslag is geconfigureerd, werkt het kanaal op dezelfde manier op alle systemen.

Notitie

Met de release 2.15.0-beta3 en hoger wordt de lokale opslag nu automatisch gemaakt voor Linux, Mac en Windows. Voor niet-Windows-systemen maakt de SDK automatisch een lokale opslagmap op basis van de volgende logica:

  • ${TMPDIR}: Als de ${TMPDIR} omgevingsvariabele is ingesteld, wordt deze locatie gebruikt.
  • /var/tmp: Als de vorige locatie niet bestaat, proberen we het ./var/tmp
  • /tmp: Als beide vorige locaties niet bestaan, proberen we het .tmp
  • Als er geen van deze locaties bestaat, wordt er geen lokale opslag gemaakt en is handmatige configuratie nog steeds vereist. Zie deze GitHub-opslagplaats voor volledige implementatiedetails.

Maakt de SDK tijdelijke lokale opslag? Worden de gegevens versleuteld in de opslag?

De SDK slaat telemetrie-items op in de lokale opslag tijdens netwerkproblemen of tijdens beperking. Deze gegevens worden niet lokaal versleuteld.

Voor Windows-systemen maakt de SDK automatisch een tijdelijke lokale map in de map %TEMP% of %LOCALAPPDATA% en beperkt de toegang tot beheerders en de huidige gebruiker alleen.

Voor andere systemen dan Windows wordt er geen lokale opslag automatisch gemaakt door de SDK. Er worden dus standaard geen gegevens lokaal opgeslagen.

Notitie

Met de release 2.15.0-beta3 en hoger wordt de lokale opslag nu automatisch gemaakt voor Linux, Mac en Windows.

U kunt zelf een opslagmap maken en het kanaal configureren voor gebruik. In dit geval bent u verantwoordelijk voor het beveiligen van de map. Lees meer over gegevensbescherming en privacy.

Opensource-SDK

Net als elke SDK voor Application Insights zijn kanalen open source. Lees en bijdragen aan de code of meld problemen in de officiële GitHub-opslagplaats.

Volgende stappen