Campionamento dei log in .NET

.NET offre funzionalità di campionamento dei log che consentono di controllare il volume dei log generati dall'applicazione senza perdere informazioni importanti. Sono disponibili le strategie di campionamento seguenti:

  • Campionamento basato su traccia: log di esempio in base alla decisione di campionamento della traccia corrente.
  • Campionamento probabilistico casuale: log di esempio basati su regole di probabilità configurate.
  • Campionamento personalizzato: implementare una strategia di campionamento personalizzata. Per altre informazioni, vedere Implementare il campionamento personalizzato.

Annotazioni

È possibile usare un solo campionatore alla volta. Se si registrano più campionatori, viene usato l'ultimo.

Il campionamento dei log estende le funzionalità di filtro offrendo un controllo più granulare sui log generati dall'applicazione. Anziché semplicemente abilitare o disabilitare i log, è possibile configurare il campionamento per generare solo una frazione di essi.

Ad esempio, mentre il filtro usa in genere probabilità come 0 (non genera log) o 1 (genera tutti i log), il campionamento consente di scegliere qualsiasi valore tra, ad esempio 0.1 per generare 10% di log o 0.25 per generare 25%.

Get started

Per iniziare, installare il 📦 pacchetto NuGet Microsoft.Extensions.Telemetry :

dotnet add package Microsoft.Extensions.Telemetry

Per altre informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Configurare il campionamento basato su traccia

Il campionamento basato su traccia garantisce che i log vengano campionati in modo coerente con l'oggetto sottostante Activity. Ciò è utile quando si vuole mantenere la correlazione tra tracce e log. È possibile abilitare il campionamento di traccia (come descritto nella guida) e quindi configurare il campionamento dei log basato su traccia di conseguenza:

builder.Logging.AddTraceBasedSampler();

Quando il campionamento basato su traccia è abilitato, i log verranno generati solo se l'oggetto sottostante Activity viene campionato. La decisione di campionamento deriva dal valore corrente Recorded .

Configurare il campionamento probabilistico casuale

Il campionamento probabilistico casuale consente di campionare i log in base alle regole di probabilità configurate. È possibile definire regole specifiche per:

  • Categoria di log
  • Livello di registrazione
  • ID evento

Esistono diversi modi per configurare il campionamento probabilistico casuale con le relative regole:

Configurazione basata su file

Creare una sezione di configurazione nel appsettings.json, ad esempio:

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

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

La configurazione precedente:

  • Campiona il 10% dei log dalle categorie che iniziano con System. di tutti i livelli.
  • Esegue un campionamento del 25% dei log dalle categorie a partire da Microsoft.AspNetCore. del LogLevel.Information.
  • Esempi 5% di log con ID evento 1001 di tutte le categorie e livelli.
  • Esempi 100% di tutti gli altri log.

Importante

Il Probability valore rappresenta la probabilità con valori compresi tra 0 e 1. Ad esempio, 0,25 indica che il 25% dei log verranno campionati. 0 indica che non verranno campionati log e 1 indica che tutti i log verranno campionati. Questi casi con 0 e 1 possono essere usati per disabilitare o abilitare in modo efficace tutti i log per una regola specifica. La probabilità non può essere minore di 0 o maggiore di 1 e, se si verifica nell'applicazione, viene generata un'eccezione.

Per registrare il campionatore con la configurazione, si consideri il codice seguente:

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

Modificare le regole di campionamento in un'app in esecuzione

Il campionamento probabilistico casuale supporta gli aggiornamenti della configurazione di runtime tramite l'interfaccia IOptionsMonitor<TOptions> . Se si usa un provider di configurazione che supporta il ricaricamento, ad esempio il provider di configurazione file, è possibile aggiornare le regole di campionamento in fase di esecuzione senza riavviare l'applicazione.

Ad esempio, è possibile avviare l'applicazione con il appsettings.jsonseguente, che funge in modo efficace da no-op:

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

Mentre l'app è in esecuzione, è possibile aggiornare il appsettings.json con la configurazione seguente:

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

Le nuove regole verranno applicate automaticamente, ad esempio, con la configurazione precedente, 1% di log con LogLevel.Information vengono campionati.

Modalità di applicazione delle regole di campionamento

L'algoritmo è molto simile al filtro dei log, ma esistono alcune differenze.

La valutazione delle regole di campionamento dei log viene eseguita su ogni record di log, ma sono presenti ottimizzazioni delle prestazioni, ad esempio la memorizzazione nella cache. L'algoritmo seguente viene usato per ogni record di log per una determinata categoria:

  • Selezionare le regole con LogLevel uguale o superiore al livello di registro del logger.
  • Selezionare le regole con EventId non definito, o definito e uguale all'ID evento del log.
  • Selezionare le regole con il prefisso della categoria corrispondente più lunga. Se non viene trovata alcuna corrispondenza, selezionare tutte le regole che non specificano una categoria.
  • Se sono selezionate più regole, scegliere l'ultima.
  • Se non sono selezionate regole, il campionamento non viene applicato, ad esempio, il record di log viene generato come di consueto.

Configurazione del codice in linea

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

La configurazione precedente:

  • Esempi 5% di log con ID evento 1001 di tutte le categorie e livelli.
  • Esempi 100% di tutti gli altri log.

Configurazione di probabilità semplice

Per gli scenari di base, è possibile configurare un singolo valore di probabilità che si applica a tutti i log al livello o al di sotto di un livello specificato:

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

Il codice precedente registra il campionatore che campionerebbe il 10% di Warning log e l'1% di Information log (e inferiori). Se la configurazione non ha la regola per Information, avrebbe campionato il 10% di Warning log e tutti i livelli sottostanti, incluso Information.

Implementare il campionamento personalizzato

È possibile creare una strategia di campionamento personalizzata derivando dalla classe astratta ed eseguendo l'override LoggingSampler dei relativi membri astratti. In questo modo è possibile personalizzare il comportamento di campionamento in base ai requisiti specifici. Ad esempio, un campionatore personalizzato potrebbe:

  • Prendere decisioni di campionamento in base alla presenza e al valore di coppie chiave/valore specifiche nello stato del log.
  • Applicare la logica di limitazione della velocità, ad esempio l'emissione di log solo se il numero di log entro un intervallo di tempo predefinito rimane al di sotto di una determinata soglia.

Per implementare un campionatore personalizzato, seguire questa procedura:

  1. Creare una classe che eredita da LoggingSampler.
  2. Eseguire l'override del LoggingSampler.ShouldSample metodo per definire la logica di campionamento personalizzata.
  3. Registrare il campionatore personalizzato nella pipeline di logging usando il AddSampler metodo di estensione.

Per ogni record di log non filtrato, il LoggingSampler.ShouldSample metodo viene chiamato esattamente una volta. Il valore restituito determina se il record di log deve essere generato.

Considerazioni sulle prestazioni

Il campionamento dei log è progettato per ridurre i costi di archiviazione, con un compromesso di un utilizzo leggermente maggiore della CPU. Se l'applicazione genera un volume elevato di log che sono costosi da archiviare, il campionamento può contribuire a ridurre tale volume. Se configurato in modo appropriato, il campionamento può ridurre i costi di archiviazione senza perdere informazioni critiche per la diagnosi degli eventi imprevisti.

Per il campionamento predefinito, vedere Benchmark.

Indicazioni su quando usare il campionamento in base al livello di log

Livello di registrazione Raccomandazione
Trace Non applicare il campionamento, perché in genere si disabilitano questi log nell'ambiente di produzione
Debug Non applicare il campionamento, perché in genere si disabilitano questi log nell'ambiente di produzione
Information Assicurati di applicare il campionamento
Warning Valutare la possibilità di applicare il campionamento
Error Non applicare il campionamento
Critical Non applicare il campionamento

Procedure consigliate

  • Iniziare con frequenze di campionamento più elevate e regolarle verso il basso in base alle esigenze.
  • Usare regole basate su categorie per specificare componenti specifici.
  • Se si usa la traccia distribuita, è consigliabile implementare il campionamento basato su traccia.
  • Monitorare l'efficacia delle regole di campionamento collettivamente.
  • Trovare il giusto equilibrio per l'applicazione: una frequenza di campionamento troppo bassa può ridurre l'osservabilità, mentre un tasso troppo elevato può aumentare i costi.

Vedere anche

  • Last updated on