Amostragem de logs em .NET

O .NET oferece capacidades de amostragem de logs que permitem controlar o volume de logs que a sua aplicação emite sem perder informações importantes. As seguintes estratégias de amostragem estão disponíveis:

• Amostragem baseada em rastros: Registos de amostra com base na decisão de amostragem do rastro atual.
• Amostragem probabilística aleatória: Amostrar logs com base em regras de probabilidade configuradas.
• Amostragem personalizada: Implemente a sua própria estratégia de amostragem personalizada. Para mais informações, consulte Implementar amostragem personalizada.

A amostragem de logs estende as capacidades de filtragem ao dar-lhe um controlo mais detalhado sobre quais logs são emitidos pela sua aplicação. Em vez de simplesmente ativar ou desativar os registos, pode configurar a amostragem para emitir apenas uma fração deles.

Por exemplo, enquanto a filtragem normalmente utiliza probabilidades como 0 (não emitir logs) ou 1 (emitir todos os logs), a amostragem permite escolher qualquer valor intermédio — como 0.1 emitir 10% de log, 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 Manage package dependencies in .NET applications.

Configurar amostragem baseada em traços

A amostragem baseada em traços garante que os registos são amostrados de forma consistente com o subjacente Activity. Isto é útil quando se quer manter a correlação entre rastros e registos. Pode ativar a amostragem de traços (conforme descrito no guia) e depois configurar a amostragem de registos baseada em traços em conformidade:

builder.Logging.AddTraceBasedSampler();

Quando a amostragem baseada em traços está ativada, os logs só serão emitidos se o subjacente Activity for amostrado. A decisão de amostragem vem do valor atual Recorded .

Configurar amostragem probabilística aleatória

A amostragem probabilística aleatória permite-lhe amostrar logs com base em regras de probabilidade configuradas. Pode definir regras específicas para:

• Categoria do log
• Nível de registo
• ID do Evento

Existem várias formas de configurar a amostragem probabilística aleatória com as 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:

• Faz amostragem de 10% dos registos de categorias que começam com System. de todos os níveis.
• Amostras de 25% de registos de categorias que começam com Microsoft.AspNetCore. o LogLevel.Information.
• Amostra 5% dos registos com ID de evento 1001 de todas as categorias e níveis.
• Amostra 100% de todos os outros registos.

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

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

Alterar regras de amostragem numa aplicação em execução

A amostragem probabilística aleatória suporta atualizações de configuração em tempo de execução através da IOptionsMonitor<TOptions> interface. Se estiver a usar um fornecedor de configuração que suporta recargas — como o File Configuration Provider — pode atualizar as regras de amostragem em tempo de execução sem reiniciar a aplicação.

Por exemplo, pode começar a sua aplicação com o seguinte appsettings.json, que funciona efetivamente como um "no-op":

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

Enquanto o aplicativo está 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 registos com os LogLevel.Information são amostrados.

Como são aplicadas as regras de amostragem

O algoritmo é muito semelhante à filtragem de log, embora existam algumas diferenças.

A avaliação das regras de amostragem de logs é realizada em cada registo log, no entanto, existem otimizações de desempenho, como cache. O seguinte algoritmo é utilizado para cada registo logarítmico de uma dada categoria:

• Selecione regras com LogLevel igual ou superior ao nível logarítmico do logger.
• Selecione regras EventId não definidas, ou que estejam definidas e sejam iguais ao ID do evento de registo.
• Selecione regras com o prefixo de categoria correspondente mais longo. Se nenhuma correspondência for localizada, selecione todas as regras que não especificam nenhuma categoria.
• Se várias regras forem selecionadas, escolha a última .
• Se não forem selecionadas regras, a amostragem não é aplicada, por exemplo, o registo logarítmico é emitido normalmente.

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 registos com ID de evento 1001 de todas as categorias e níveis.
• Amostra 100% de todos os outros registos.

Configuração simples de probabilidade

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

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

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

Implementar amostragem personalizada

Pode criar uma estratégia de amostragem personalizada derivando da classe abstrata LoggingSampler e sobrescrevendo os seus membros abstratos. Isto permite-lhe adaptar o comportamento de amostragem às suas necessidades específicas. Por exemplo, um sampler personalizado poderia:

• Tome decisões de amostragem com base na presença e valor de pares chave/valor específicos no estado logarítmico.
• Aplique lógica de limitação de taxa, como emitir registos apenas se o número de registos dentro de um intervalo de tempo predefinido se mantiver abaixo de um determinado limiar.

Para implementar um sampler personalizado, siga estes passos:

1. Crie uma classe que herda do LoggingSampler.
2. Sobreponha o método LoggingSampler.ShouldSample para definir a tua lógica de amostragem personalizada.
3. Registe o seu sampler personalizado no pipeline de logging usando o método de extensão AddSampler.

Para cada registo de log que não é filtrado, o método LoggingSampler.ShouldSample é invocado exatamente uma vez. O valor devolvido determina se o registo de log deve ser emitido.

Considerações sobre desempenho

A amostragem de registos foi concebida para reduzir os custos de armazenamento, com a troca de um ligeiro aumento da utilização da CPU. Se a sua aplicação gerar um grande volume de registos que são caros de armazenar, a amostragem pode ajudar a reduzir esse volume. Quando configurada adequadamente, a amostragem pode reduzir os custos de armazenamento sem perder informação crítica para o diagnóstico de incidentes.

Para a amostragem integrada, consulte Benchmarks.

Orientação ao nível de logaritário sobre quando usar a amostragem

Melhores práticas

• Comece com taxas de amostragem mais elevadas e ajuste-as para baixo conforme necessário.
• Use regras baseadas em categorias para direcionar componentes específicos.
• Se estiver a usar rastreamento distribuído, considere implementar amostragem baseada em traços.
• Monitorizem coletivamente a eficácia das vossas regras de amostragem.
• Encontre o equilíbrio certo para a sua aplicação — uma taxa de amostragem demasiado baixa pode reduzir a observabilidade, enquanto uma taxa demasiado alta pode aumentar os custos.

Consulte também

• Registo em .NET
• Registo de alto desempenho no .NET
• Rastreamento de Amostragem do OpenTelemetry