Partager via

Canaux de télémétrie dans Application Insights

Les canaux de télémétrie font partie intégrante des SDK Application Insights. Ils gèrent la mise en mémoire tampon des données de télémétrie et leur transmission au service Application Insights. Les versions .NET et .NET Core des SDK intègrent deux canaux de télémétrie : InMemoryChannel et ServerTelemetryChannel. Cet article décrit chaque canal et montre comment personnaliser leur comportement.

Attention

Nous recommandons la distribution OpenTelemetry Azure Monitor pour les nouvelles applications ou les nouveaux clients afin d’alimenter Azure Monitor Application Insights. La distribution OpenTelemetry Azure Monitor offre une expérience et des fonctionnalités similaires à celles du SDK Application Insights. Il est possible de migrer depuis le Kit de développement logiciel (SDK) Application Insights en utilisant les guides de migration pour .NET, Node.js et Python, mais nous travaillons encore à l’ajout de quelques fonctionnalités supplémentaires pour la compatibilité descendante.

Que sont les canaux de télémétrie ?

Les canaux de télémétrie gèrent la mise en mémoire tampon des éléments de télémétrie et la transmission de ces éléments au service Application Insights, où ils sont stockés pour être interrogés et analysés. Un canal de télémétrie est une classe qui implémente l’interface Microsoft.ApplicationInsights.ITelemetryChannel.

La méthode Send(ITelemetry item) d’un canal de télémétrie est appelée une fois que tous les initialiseurs et processeurs de télémétrie ont été appelés. Par conséquent, tous les éléments supprimés par un processeur de télémétrie n’atteignent pas le canal. La méthode Send() n’envoie généralement pas instantanément les éléments au back-end. Il les place généralement en mémoire tampon et les envoie par lots pour optimiser leur transmission.

Évitez d’appeler Flush() , sauf s’il est essentiel d’envoyer immédiatement des données de télémétrie mises en mémoire tampon. Utilisez-le uniquement dans des scénarios tels que l’arrêt de l’application, la gestion des exceptions ou lors de l’utilisation de processus de courte durée, tels que des travaux en arrière-plan ou des outils en ligne de commande. Dans les applications web ou les services de longue durée, le SDK gère automatiquement l’envoi de données de télémétrie. Appeler Flush() inutilement peut entraîner des problèmes de performance.

Le flux de métriques temps réel a également un canal personnalisé pour le streaming en direct des données de télémétrie. Le présent document ne s’applique pas à ce canal, qui est indépendant du canal de télémétrie standard.

Canaux de télémétrie intégrés

Les kits SDK .NET et .NET Core d’Application Insights intègrent deux canaux :

  • InMemoryChannel: un canal léger qui stocke les éléments en mémoire jusqu'à leur envoi. Les éléments sont mis en mémoire tampon et vidés toutes les 30 secondes, ou dès que la mémoire tampon atteint 500 éléments. Ce canal offre des garanties de fiabilité minimales, car il ne retente pas l’envoi des éléments de télémétrie après un échec. Ce canal ne conserve pas non plus les éléments sur le disque. Ainsi, tous les éléments non envoyés sont perdus définitivement lors de l’arrêt de l’application, qu’il soit approprié ou non. Il implémente une méthode Flush() qui permet de forcer le vidage synchrone des éléments de télémétrie de la mémoire. Ce canal est bien adapté aux applications de courte durée où une purge synchrone est idéale.

    Ce canal fait partie du package NuGet Microsoft.ApplicationInsights plus grand et constitue le canal par défaut utilisé par le SDK si aucune autre configuration n’a été spécifiée.

  • ServerTelemetryChannel: canal plus avancé qui offre des stratégies de nouvelles tentatives et la capacité de stocker des données sur un disque local. Ce canal tente à nouveau d’envoyer les données de télémétrie si des erreurs temporaires se produisent. Ce canal utilise également le stockage sur disque local pour conserver les éléments sur le disque durant les pannes réseau ou les volumes élevés de télémétrie. Grâce aux stratégies de nouvelles tentatives et au stockage sur disque local, ce canal est considéré comme plus fiable. Nous le recommandons pour tous les scénarios de production. Ce canal est utilisé par défaut pour les applications ASP.NET et ASP.NET Core qui sont configurées conformément à la documentation officielle. Il est optimisé pour les scénarios de serveur exécutant des processus de longue durée. La méthode Flush() implémentée par ce canal n’est pas synchrone.

    Ce canal est fourni dans le package NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel et est activé automatiquement quand vous utilisez le package NuGet Microsoft.ApplicationInsights.Web ou Microsoft.ApplicationInsights.AspNetCore.

Configurer un canal de télémétrie

Vous configurez un canal de télémétrie en l’ajoutant à la configuration de télémétrie active. Pour les applications ASP.NET, la configuration implique de définir l’instance du canal de télémétrie sur TelemetryConfiguration.Active, ou de modifier ApplicationInsights.config. Pour les applications ASP.NET Core, la configuration implique d’ajouter le canal au conteneur d’injection de dépendance.

Les sections suivantes présentent des exemples de configuration du paramètre StorageFolder pour le canal dans différents types d’applications. StorageFolder est juste l’un des paramètres configurables. Pour obtenir la liste complète des paramètres de configuration, consultez la section des paramètres configurables dans les canaux plus loin dans cet article.

Configuration avec ApplicationInsights.config pour les applications ASP.NET

L’extrait suivant du fichier ApplicationInsights.config montre le canal ServerTelemetryChannel dont le paramètre StorageFolder est défini à un emplacement personnalisé :

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

Configuration dans le code pour les applications ASP.NET

Le code suivant configure une instance ServerTelemetryChannel avec le paramètre StorageFolder défini à un emplacement personnalisé. Ajoutez ce code au début de l’application, généralement dans la méthode Application_Start() dans 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;
}

Configuration dans le code pour les applications ASP.NET Core

Modifiez la méthode ConfigureServices de la classe Startup.cs comme indiqué ici :

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

Important

La configuration du canal avec TelemetryConfiguration.Active n’est pas prise en charge pour les applications ASP.NET Core.

Configuration dans le code pour les applications console .NET/.NET Core

Pour les applications console, le code est identique pour .NET et .NET Core :

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

Détails du fonctionnement de ServerTelemetryChannel

ServerTelemetryChannel stocke les éléments entrants dans la mémoire tampon. Les éléments sont sérialisés, compressés et stockés dans une instance Transmission toutes les 30 secondes, ou dès que la mémoire tampon atteint 500 éléments. Une seule instance Transmission peut contenir jusqu’à 500 éléments de télémétrie, constituant un lot qui est envoyé au service Application Insights par le biais d’un appel HTTPS unique.

Par défaut, un maximum de 10 instances Transmission peuvent être envoyées en parallèle. Si les données de télémétrie arrivent à un rythme plus rapide, ou si le réseau ou le serveur back-end Application Insights est lent, les instances Transmission sont mises en mémoire tampon. La capacité par défaut de cette mémoire tampon Transmission est de 5 Mo. En cas de dépassement de la capacité mémoire, les instances Transmission sont stockées sur le disque local à hauteur de 50 Mo.

Les instances Transmission sont également stockées sur le disque local quand des problèmes réseau se produisent. Seuls les éléments stockés sur un disque local sont conservés après un plantage de l’application. Ils sont envoyés au redémarrage de l’application. Si les problèmes réseau persistent, ServerTelemetryChannel utilise une logique d’interruption exponentielle allant de 10 secondes à 1 heure avant de réessayer d’envoyer des données de télémétrie.

Paramètres configurables dans les canaux

Pour obtenir la liste complète des paramètres configurables de chaque canal, consultez :

Voici les paramètres les plus couramment utilisés pour ServerTelemetryChannel :

  • MaxTransmissionBufferCapacity: quantité de mémoire maximale, en octets, utilisée par le canal pour mettre en mémoire tampon les données avant leur transmission. Quand cette limite de capacité est atteinte, les nouveaux éléments sont stockés directement sur le disque local. La valeur par défaut est 5 Mo. Si vous définissez une valeur plus élevée pour réduire l’utilisation du disque, n’oubliez pas que les éléments en mémoire seront perdus en cas de plantage de l’application.
  • MaxTransmissionSenderCapacity: nombre maximal d’instances Transmission envoyées simultanément à Application Insights. La valeur par défaut est 10. Ce paramètre peut être défini à un nombre plus élevé, ce qui est d’ailleurs recommandé si un gros volume de données de télémétrie doit être généré. Un volume élevé se produit habituellement pendant les tests de charge ou lorsque l'échantillonnage est désactivé.
  • StorageFolder: dossier utilisé par le canal pour stocker les éléments sur le disque en fonction des besoins. Dans Windows, le dossier %LOCALAPPDATA% ou %TEMP% est utilisé si aucun autre chemin n’a été spécifié explicitement. Dans les autres environnements que Windows, vous devez spécifier un emplacement valide, car sinon les données de télémétrie ne seront pas stockées sur le disque local.

Quel canal dois-je utiliser ?

Nous recommandons ServerTelemetryChannel pour la plupart des scénarios de production qui impliquent des applications de longue durée. Pour plus d’informations sur l’effacement des données de télémétrie, lisez l’article concernant l’utilisation de Flush().

Quand utiliser Flush()

La Flush() méthode envoie immédiatement toutes les données de télémétrie mises en mémoire tampon. Toutefois, elle ne doit être utilisée que dans des scénarios spécifiques.

Utilisez Flush() quand :

  • L’application est sur le point d’arrêter et vous souhaitez vous assurer que la télémétrie est envoyée avant la sortie.
  • Vous êtes dans un gestionnaire d’exceptions et devez vous assurer de la transmission de la télémétrie.
  • Vous écrivez un processus de courte durée comme un travail en arrière-plan ou un outil CLI qui se termine rapidement.

Évitez d’utiliser Flush() dans des applications longues telles que des services web. Le Kit de développement logiciel (SDK) gère automatiquement la mise en mémoire tampon et la transmission. L’appel Flush() inutilement peut entraîner des problèmes de performances et ne garantit pas que toutes les données sont envoyées, en particulier lors de l’utilisation ServerTelemetryChannel, qui ne se vide pas de manière synchrone.

Kit de développement logiciel (SDK) open source

Comme chaque SDK pour Application Insights, les canaux sont open source. Lisez et contribuez au code, ou signalez les problèmes rencontrés dans le dépôt GitHub officiel.

Étapes suivantes