Échantillonnage des journaux dans .NET

.NET fournit des fonctionnalités d’échantillonnage de journaux qui vous permettent de contrôler le volume de journaux émis par votre application sans perdre les informations importantes. Les stratégies d’échantillonnage suivantes sont disponibles :

  • Échantillonnage basé sur les traces : journaliser des échantillons basés sur la décision d’échantillonnage de la trace courante.
  • Échantillonnage probabiliste aléatoire : échantillons de journaux basés sur des règles de probabilité configurées.
  • Échantillonnage personnalisé : implémentez votre propre stratégie d’échantillonnage personnalisée. Pour plus d’informations, consultez Implémenter un échantillonnage personnalisé.

Note

Un seul échantillonneur peut être utilisé à la fois. Si vous inscrivez plusieurs échantillonneurs, le dernier est utilisé.

L'échantillonnage des logs étend les fonctionnalités de filtrage en vous offrant un contrôle plus précis sur les logs émis par votre application. Au lieu de simplement activer ou désactiver les logs, vous pouvez configurer un échantillonnage pour générer uniquement une fraction d’entre eux.

Par exemple, alors que le filtrage utilise généralement des probabilités telles que 0 (n'émettre aucun journal) ou 1 (émettre tous les journaux), l'échantillonnage vous permet de choisir une valeur intermédiaire, par exemple 0.1 pour émettre 10 % des journaux, ou 0.25 pour émettre 25 %.

Get started

Pour commencer, installez le 📦 package NuGet Microsoft.Extensions.Telemetry :

dotnet add package Microsoft.Extensions.Telemetry

Pour plus d’informations, consultez dotnet add package or Manage package dependencies in .NET applications.

Configurer l’échantillonnage basé sur les traces

L’échantillonnage basé sur la trace garantit que les logs sont échantillonnés en cohérence avec l'élément sous-jacent Activity. Cela est utile lorsque vous souhaitez maintenir la corrélation entre les traces et les journaux. Vous pouvez activer l’échantillonnage de trace (comme décrit dans le guide), puis configurer l’échantillonnage de journal basé sur la trace en conséquence :

builder.Logging.AddTraceBasedSampler();

Lorsque l’échantillonnage basé sur les traces est activé, les journaux de log sont émis uniquement si le sous-jacent Activity est échantillonné. La décision d’échantillonnage provient de la valeur actuelle Recorded .

Configurer l’échantillonnage probabiliste aléatoire

L’échantillonnage probabiliste aléatoire vous permet d’échantillonner des logs selon des règles de probabilité configurées. Vous pouvez définir des règles spécifiques à :

  • Catégorie de journal
  • Niveau de journalisation
  • ID de l’événement

Il existe plusieurs façons de configurer l’échantillonnage probabiliste aléatoire avec ses règles :

Configuration basée sur des fichiers

Créez une section de configuration dans votre appsettings.json, par exemple :

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  },

  "RandomProbabilisticSampler": {
    "Rules": [
      {
        "CategoryName": "Microsoft.AspNetCore.*",
        "Probability": 0.25,
        "LogLevel": "Information"
      },
      {
        "CategoryName": "System.*",
        "Probability": 0.1
      },
      {
        "EventId": 1001,
        "Probability": 0.05
      }
    ]
  }
}

Configuration précédente :

  • Échantillonne 10% des journaux des catégories de tous les niveaux, commençant par System..
  • Échantillonne 25% des journaux d'activité à partir des catégories commençant par Microsoft.AspNetCore. le LogLevel.Information.
  • Échantillonne 5 % des journaux de bord avec l’ID d’événement 1001 de toutes les catégories et de tous les niveaux.
  • Échantillonne 100% de tous les autres logs.

Important

La Probability valeur représente la probabilité avec les valeurs comprises entre 0 et 1. Par exemple, 0,25 signifie que 25 % des journaux seront échantillonnés. 0 signifie qu’aucun journal n’est échantillonné, et 1 signifie que tous les journaux sont échantillonnés. Ces cas avec 0 et 1 peuvent être utilisés pour désactiver ou activer efficacement tous les journaux d’activité pour une règle spécifique. La probabilité ne peut pas être inférieure à 0 ou supérieure à 1 et, si cela se produit dans l’application, une exception est levée.

Pour inscrire l’échantillonneur avec la configuration, tenez compte du code suivant :

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

Modifier les règles d’échantillonnage dans une application en cours d’exécution

L’échantillonnage probabiliste aléatoire prend en charge les mises à jour de configuration du runtime via l’interface IOptionsMonitor<TOptions> . Si vous utilisez un fournisseur de configuration qui prend en charge les rechargements, tels que le fournisseur de configuration de fichiers, vous pouvez mettre à jour les règles d’échantillonnage au moment de l’exécution sans redémarrer l’application.

Par exemple, vous pouvez démarrer votre application avec la appsettings.jsonsuivante, qui agit efficacement comme un no-op:

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 1
        }
      ]
    }
  }
}

Pendant l’exécution de l’application, vous pouvez mettre à jour le appsettings.json avec la configuration suivante :

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 0.01,
          "LogLevel": "Information"
        }
      ]
    }
  }
}

Les nouvelles règles seront appliquées automatiquement, par exemple, avec la configuration précédente, 1% de journaux avec le LogLevel.Information sont échantillonnés.

Comment les règles d’échantillonnage sont appliquées

L’algorithme est très similaire au filtrage de logs, mais il existe des différences.

L’évaluation des règles d’échantillonnage des journaux est effectuée sur chaque enregistrement de journal, mais des optimisations de performance sont mises en place, par exemple la mise en cache. L’algorithme suivant est utilisé pour chaque enregistrement de journal pour une catégorie donnée :

  • Sélectionnez des règles avec LogLevel égales à ou supérieures au niveau de journalisation du logger.
  • Sélectionnez des règles avec EventId non définies ou définies et égales à l’ID d’événement du journal.
  • Sélectionnez des règles avec le préfixe de catégorie correspondant le plus long. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles qui ne spécifient pas de catégorie.
  • Si plusieurs règles sont sélectionnées, prenez la dernière.
  • Si aucune règle n’est sélectionnée, l’échantillonnage n’est pas appliqué, par exemple, l’enregistrement du journal est émis comme d’habitude.

Configuration du code inline

builder.Logging.AddRandomProbabilisticSampler(options =>
{
    options.Rules.Add(
        new RandomProbabilisticSamplerFilterRule(
            probability: 0.05d,
            eventId : 1001));
});

Configuration précédente :

  • Échantillonne 5 % des journaux de bord avec l’ID d’événement 1001 de toutes les catégories et de tous les niveaux.
  • Échantillonne 100% de tous les autres logs.

Configuration de probabilité simple

Pour les scénarios de base, vous pouvez configurer une valeur de probabilité unique qui s’applique à tous les journaux d’activité au niveau spécifié ou inférieur à un niveau spécifié :

builder.Logging.AddRandomProbabilisticSampler(0.01, LogLevel.Information);
builder.Logging.AddRandomProbabilisticSampler(0.1, LogLevel.Warning);

Le code ci-dessus enregistre l’échantillonneur qui échantillonnerait 10% de Warning journaux et 1% des Information journaux (et ci-dessous). Si la configuration n’avait pas la règle pour Information, elle aurait échantillonné 10% des journaux de logs de Warning et tous les niveaux inférieurs, y compris Information.

Implémenter un échantillonnage personnalisé

Vous pouvez créer une stratégie d’échantillonnage personnalisée en dérivant de la LoggingSampler classe abstraite et en substituant ses membres abstraits. Cela vous permet d’adapter le comportement d’échantillonnage à vos besoins spécifiques. Par exemple, un échantillonneur personnalisé peut :

  • Prenez des décisions d’échantillonnage en fonction de la présence et de la valeur des paires clé/valeur spécifiques dans l’état du journal.
  • Appliquez une logique de limitation de débit, telle que l’émission de logs uniquement si le nombre de logs dans un intervalle de temps prédéfini reste inférieur à un certain seuil.

Pour implémenter un échantillonneur personnalisé, procédez comme suit :

  1. Créez une classe qui hérite de LoggingSampler.
  2. Remplacez la LoggingSampler.ShouldSample méthode pour définir votre logique d’échantillonnage personnalisée.
  3. Inscrivez votre échantillonneur personnalisé dans le pipeline de journalisation à l’aide de la méthode d’extension AddSampler .

Pour chaque enregistrement de journal qui n’est pas filtré, la LoggingSampler.ShouldSample méthode est appelée exactement une seule fois. Sa valeur de retour détermine si l’enregistrement du journal doit être émis.

Considérations relatives aux performances

L’échantillonnage des journaux est conçu pour réduire les coûts de stockage, au prix d'une utilisation légèrement accrue du processeur. Si votre application génère un volume élevé de journaux d’activité coûteux à stocker, l’échantillonnage peut aider à réduire ce volume. En cas de configuration appropriée, l’échantillonnage peut réduire les coûts de stockage sans perdre des informations essentielles pour diagnostiquer les incidents.

Pour l’échantillonnage intégré, consultez Benchmarks.

Conseils sur le niveau de log pour l'utilisation de l'échantillonnage

Niveau de journalisation Recommandation
Trace N'appliquez pas d'échantillonnage car, en général, vous désactivez ces journaux en production.
Debug N'appliquez pas d'échantillonnage car, en général, vous désactivez ces journaux en production.
Information Veuillez appliquer l'échantillonnage
Warning Envisagez d’appliquer l’échantillonnage
Error Ne pas appliquer l’échantillonnage
Critical Ne pas appliquer l’échantillonnage

Meilleures pratiques

  • Commencez par des taux d’échantillonnage plus élevés et ajustez-les à la baisse si nécessaire.
  • Utilisez des règles basées sur des catégories pour cibler des composants spécifiques.
  • Si vous utilisez le suivi distribué, envisagez d’implémenter l’échantillonnage basé sur les traces.
  • Surveillez collectivement l’efficacité de vos règles d’échantillonnage.
  • Trouvez le bon équilibre pour votre application : un taux d’échantillonnage trop faible peut réduire l’observabilité, tandis qu’un taux trop élevé peut augmenter les coûts.

Voir aussi

  • Last updated on