Amostragem de log no .NET

O .NET fornece recursos de amostragem de log que permitem controlar o volume de logs que seu aplicativo emite sem perder informações importantes. As seguintes estratégias de amostragem estão disponíveis:

• Amostragem baseada em rastreamento: amostrar logs com base na decisão de amostragem do traço atual.
• Amostragem probabilística aleatória: logs de exemplo com base em regras de probabilidade configuradas.
• Amostragem personalizada: implemente sua própria estratégia de amostragem personalizada. Para obter mais informações, consulte Implementar amostragem personalizada.

A amostragem de log estende os recursos de filtragem, proporcionando um controle mais refinado sobre quais logs são emitidos por sua aplicação. Em vez de simplesmente habilitar ou desabilitar logs, você pode configurar a amostragem para emitir apenas uma fração deles.

Por exemplo, enquanto a filtragem normalmente usa probabilidades como 0 (não emitir logs) ou 1 (emitir todos os logs), a amostragem permite que você escolha qualquer valor entre eles, como 0.1 emitir 10% de logs ou 0.25 emitir 25%.

Introdução

Para começar, instale o 📦 pacote NuGet Microsoft.Extensions.Telemetry :

dotnet add package Microsoft.Extensions.Telemetry

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Telemetry"
                    Version="*" />
</ItemGroup>

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em aplicativos .NET.

Configurar amostragem baseada em rastreamento

A amostragem por rastreamento assegura que os logs sejam coletados de maneira consistente com o sistema subjacente Activity. Isso é útil quando você deseja manter a correlação entre rastreamentos e logs. Você pode habilitar a amostragem de rastreamento (conforme descrito no guia) e, em seguida, configurar a amostragem de log baseada em rastreamento de acordo:

builder.Logging.AddTraceBasedSampler();

Quando a amostragem baseada em rastreamento estiver habilitada, os logs serão emitidos somente se a amostragem Activity subjacente for amostrada. A decisão de amostragem vem do valor atual Recorded .

Configurar amostragem probabilística aleatória

A amostragem probabilística aleatória permite que você amostre logs com base em regras de probabilidade configuradas. Você pode definir regras específicas para:

• Categoria do log
• Nível de log
• ID do evento

Há várias maneiras de configurar a amostragem probabilística aleatória com suas regras:

Configuração baseada em arquivo

Crie uma seção de configuração em seu appsettings.json, por exemplo:

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

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

A configuração anterior:

• Amostra 10% dos logs de categorias começando com System. de todos os níveis.
• 25% dos logs de categorias começando com Microsoft.AspNetCore. do LogLevel.Information.
• Amostra 5% dos logs com ID de evento 1001 de todas as categorias e níveis.
• Analisa 100% de todos os outros logs.

Para registrar o sampler com a configuração, considere o seguinte código:

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

Alterar regras de amostragem em um aplicativo em execução

A amostragem probabilística aleatória dá suporte a atualizações de configuração de runtime por meio da IOptionsMonitor<TOptions> interface. Se você estiver usando um provedor de configuração que dê suporte a recarregamentos, como o Provedor de Configuração de Arquivos, poderá atualizar as regras de amostragem em runtime sem reiniciar o aplicativo.

Por exemplo, você pode iniciar seu aplicativo com o seguinte appsettings.json, que atua efetivamente como um no-op:

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

Enquanto o aplicativo estiver em execução, você pode atualizar o appsettings.json com a seguinte configuração:

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

As novas regras serão aplicadas automaticamente, por exemplo, com a configuração anterior, 1% de logs com o LogLevel.Information são amostrados.

Como as regras de amostragem são aplicadas

O algoritmo é muito semelhante à filtragem de log, mas há algumas diferenças.

A avaliação das regras de amostragem de log é executada em cada registro de log; no entanto, as otimizações de desempenho, como o armazenamento em cache, estão em vigor. O algoritmo a seguir é usado para cada registro de log para uma determinada categoria:

• Selecione regras com LogLevel igual ou superior ao nível de log do registrador.
• Selecione regras que não estejam EventId definidas ou que estejam definidas e iguais à ID de evento de log.
• Selecione regras com o prefixo de categoria correspondente mais longo. Se nenhuma correspondência for encontrada, selecione todas as regras que não especificam uma categoria.
• Se várias regras forem selecionadas, use a última.
• Se nenhuma regra for selecionada, a amostragem não será aplicada, por exemplo, o registro de log será emitido como de costume.

Configuração de código em linha

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

A configuração anterior:

• Amostra 5% dos logs com ID de evento 1001 de todas as categorias e níveis.
• Analisa 100% de todos os outros logs.

Configuração de probabilidade simples

Para cenários básicos, você pode configurar um único valor de probabilidade que se aplica a todos os logs em ou abaixo de um nível especificado:

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

O código acima registra o sampler que amostraria 10% de Warning logs e 1% de Information logs (e abaixo). Se a configuração não tivesse a regra para Information, ela teria amostrado 10% de Warning logs e todos os níveis abaixo, incluindo Information.

Implementar amostragem personalizada

Você pode criar uma estratégia de amostragem personalizada derivando da LoggingSampler classe abstrata e substituindo seus membros abstratos. Isso permite que você adapte o comportamento de amostragem aos seus requisitos específicos. Por exemplo, um sampler personalizado pode:

• Tome decisões de amostragem com base na presença e no valor de pares chave/valor específicos no estado do log.
• Aplique a lógica de limitação de taxa, como emitir logs somente se o número de logs dentro de um intervalo de tempo predefinido permanecer abaixo de um determinado limite.

Para implementar um sampler personalizado, siga estas etapas:

1. Criar uma classe que herda de LoggingSampler.
2. Sobrescreva o LoggingSampler.ShouldSample método para definir sua lógica de amostragem personalizada.
3. Registre seu sampler personalizado no pipeline de log usando o método de extensão AddSampler.

Para cada registro de log que não é filtrado, o LoggingSampler.ShouldSample método é chamado exatamente uma vez. Seu valor retornado determina se o registro de log deve ser emitido.

Considerações sobre desempenho

A amostragem de log foi projetada para reduzir os custos de armazenamento, com uma compensação de um uso ligeiramente maior da CPU. Se o aplicativo gerar um alto volume de logs que são caros de armazenar, a amostragem poderá ajudar a reduzir esse volume. Quando configurada adequadamente, a amostragem pode reduzir os custos de armazenamento sem perder informações críticas para diagnosticar incidentes.

Para a amostragem embutida, consulte Benchmarks.

Diretrizes de nível de log sobre quando usar amostragem

Práticas recomendadas

• Comece com taxas de amostragem mais altas e ajuste-as para baixo conforme necessário.
• Use regras baseadas em categoria para direcionar componentes específicos.
• Se você estiver usando o rastreamento distribuído, considere implementar a amostragem baseada em rastreamento.
• Monitore a eficácia de suas regras de amostragem coletivamente.
• Encontre o equilíbrio certo para seu aplicativo— uma taxa de amostragem muito baixa pode reduzir a observabilidade, enquanto uma taxa muito alta pode aumentar os custos.

Consulte também

• Registro em log no .NET
• Registro em log de alto desempenho no .NET
• Amostragem de rastreamento opentelemetry