Rotação de arquivos de log no Serilog: intervalos e retenção

Passe rollingInterval para o sink de arquivo e o Serilog inicia um novo arquivo nesse intervalo: .WriteTo.File("logs/log.txt", rollingInterval: RollingInterval.Day) gera log20260824.txt, log20260825.txt e assim por diante.

Outras duas opções decidem por quanto tempo isso continua administrável. retainedFileCountLimit limita quantos arquivos são mantidos antes que o mais antigo seja excluído, e fileSizeLimitBytes com rollOnFileSizeLimit inicia um novo arquivo quando o atual fica grande demais. Sem o segundo deles, o sink simplesmente para de gravar quando o limite é atingido.

Para um guia mais detalhado sobre o Serilog, consulte o artigo sobre boas práticas de logging com Serilog no .NET.

Primeiros passos com o sink de arquivo do Serilog

Primeiro, vamos configurar uma aplicação ASP.NET Core MVC simples. Precisamos instalar os pacotes NuGet Serilog.Sinks.File e Serilog.AspNetCore:

PM> Install-Package Serilog.Sinks.File -Version 7.0.0

PM> Install-Package Serilog.AspNetCore -Version 10.0.0

Para continuar, vejamos como configurar o logging em arquivos com rotação no Serilog. Fazemos isso no arquivo principal, Program.cs:

using Serilog;

Log.Logger = new LoggerConfiguration()
    .WriteTo.File("logs/log.txt",
    rollingInterval: RollingInterval.Day,
    rollOnFileSizeLimit: true)
    .CreateLogger();

Configuramos o parâmetro rollingInterval para usar RollingInterval.Day, o que garante que um novo arquivo de log seja criado a cada dia. Além disso, ativamos a rotação por tamanho de arquivo definindo rollOnFileSizeLimit como true.

Atribuir a configuração a Log.Logger é só metade da integração. Os loggers que os controladores recebem vêm do próprio sistema de logging do host, então também o direcionamos para o Serilog:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

builder.Host.UseSerilog();

UseSerilog() vem no pacote Serilog.AspNetCore e, sem argumentos, encaminha tudo pelo Log.Logger estático que configuramos acima. Esta também é a etapa que coloca o Serilog por trás da API ILogger da Microsoft, de modo que nada no código da aplicação precisa saber que o Serilog está ali.

Com a configuração pronta, vamos navegar até o diretório Controllers e abrir a classe HomeController. Nela, podemos adicionar um logger pelo construtor e atualizar o código do método Index:

private readonly ILogger<HomeController> _logger;

public HomeController(ILogger<HomeController> logger)
{
    _logger = logger;
}

public IActionResult Index()
{
    _logger.LogInformation("TESTING MESSAGE 123..");

    return View();
}

O método Index registra uma mensagem de nível informativo por meio de _logger, um ILogger<HomeController> que o framework injeta no construtor. Esse logger injetado só chega ao nosso arquivo por causa da chamada a UseSerilog() acima.

Ao executar a aplicação e navegar um pouco por ela, devemos ver que um novo diretório logs foi criado na raiz do projeto:

O diretório logs contém arquivos de log nomeados de acordo com o ponto de rotação, por exemplo, log20260824.txt. Pela nossa configuração, a aplicação cria um novo arquivo de log a cada dia. Ao abrir esse arquivo, encontramos a nossa entrada informativa entre as mensagens de inicialização do próprio host:

2026-08-24 00:17:11.927 +02:00 [INF] TESTING MESSAGE 123..

O formato dessa linha vem do modelo de saída (output template) padrão do sink, que o parâmetro outputTemplate substitui quando queremos outro. O texto depois do nível é a mensagem renderizada, e é por causa dela que vale a pena escrever os modelos de mensagem corretamente.

Quais são os valores de RollingInterval no Serilog?

RollingInterval é uma enumeração com seis valores: Infinite, Year, Month, Day, Hour e Minute.

Infinite é o padrão e significa exatamente o que diz: o arquivo nunca é rotacionado, e nenhuma informação de data ou hora é acrescentada ao nome do arquivo.

Os outros cinco definem o ponto em que um novo arquivo começa, e cada um também define o formato do nome do arquivo. Day gera log20260824.txt; Hour gera log2026082414.txt; Minute acrescenta os minutos. A data é inserida antes da extensão, então o caminho que passamos é um modelo, e não um nome de arquivo literal.

A escolha depende de quanto um único arquivo cresce. Day atende à maioria das aplicações. Hour é indicado para serviços de alto volume, em que um arquivo diário ficaria grande demais para ser aberto com conforto. Month e Year servem para tarefas em segundo plano de baixo volume, em que um arquivo diário ficaria quase sempre vazio.

Políticas de rotação no sink de arquivo do Serilog

O pacote NuGet Serilog.Sinks.File oferece várias políticas de rotação para controlar a criação de novos arquivos de log. Vejamos as que os desenvolvedores costumam usar:

• RollingInterval
• FileSizeLimitBytes
• RetainedFileCountLimit
• RollOnFileSizeLimit

RollingInterval

Esta política especifica o intervalo de tempo após o qual um novo arquivo de log deve ser criado. As opções disponíveis são os seis membros da enumeração: RollingInterval.Infinite, RollingInterval.Year, RollingInterval.Month, RollingInterval.Day, RollingInterval.Hour e RollingInterval.Minute. Infinite é o padrão, então um sink de arquivo configurado sem esse parâmetro simplesmente nunca faz a rotação por tempo. O código-fonte de RollingInterval do próprio Serilog.Sinks.File documenta esse valor assim: “O arquivo de log nunca será rotacionado; nenhuma informação de período de tempo será acrescentada ao nome do arquivo de log.”

Veja a implementação de exemplo que temos na seção Primeiros passos.

FileSizeLimitBytes

O objetivo de definir FileSizeLimitBytes é controlar o tamanho máximo de cada arquivo de log:

    var log = new LoggerConfiguration()
    .WriteTo.File("logs/log.txt",
      fileSizeLimitBytes: 524288000,
      rollOnFileSizeLimit: true)
      .CreateLogger();

Ao especificar um limite de tamanho de arquivo com o parâmetro fileSizeLimitBytes e, além disso, definir o parâmetro rollOnFileSizeLimit como true, garantimos que os arquivos de log não cresçam indefinidamente a ponto de ficarem grandes demais para gerenciar e consultar com eficiência. O README do sink informa o padrão com todas as letras: “o sink de arquivo limita o tamanho do arquivo a 1 GB por padrão”. Os desenvolvedores costumam achar mais fácil pesquisar, analisar e diagnosticar problemas em arquivos de log menores usando um visualizador.

Quando atingimos o limite de 500 megabytes (524.288.000 bytes), o Serilog cria um novo arquivo de log e continua gravando os logs nele.

RetainedFileCountLimit

Os desenvolvedores consideram esta política importante. Com ela, especificamos o número máximo de arquivos de log que devem ser mantidos:

var log = new LoggerConfiguration()
    .WriteTo.File("logs/log.txt",
     retainedFileCountLimit: 21,
     rollingInterval: RollingInterval.Day)
     .CreateLogger();

Com essa configuração, garantimos que os arquivos de log antigos sejam removidos de acordo com o parâmetro retainedFileCountLimit. O valor padrão é 31, cerca de um mês cheio, como registra o README do sink (consultado em 13 de setembro de 2026). O arquivo de log mais antigo é excluído se o número de arquivos ultrapassar esse limite.

RollOnFileSizeLimit

Em relação à política de rotação FileSizeLimitBytes, definir rollOnFileSizeLimit como true faz com que um novo arquivo de log seja criado quando atingimos o limite especificado em fileSizeLimitBytes.

Por outro lado, se não ativarmos a rotação por tamanho de arquivo, definindo a propriedade como false, o sink para de gravar novos eventos no arquivo assim que o limite é atingido. É importante estar ciente disso, pois pode resultar em perda de informações.

O sink de arquivo do Serilog cria o diretório?

Sim. O sink cria os diretórios que faltam no caminho quando abre o primeiro arquivo, então logs/log.txt funciona sem que precisemos criar logs antes.

É por isso que uma pasta logs aparece na raiz do projeto logo depois da primeira execução da aplicação de exemplo: nada a criou além do próprio sink.

Há duas coisas que ele não faz. Não coloca a data no nome de uma pasta, então logs/{Date}/log.txt cria uma pasta chamada literalmente {Date}. Também não corrige um caminho em que o processo não tem permissão de gravação. O segundo caso falha no momento da gravação e, por padrão, o Serilog falha silenciosamente em vez de lançar uma exceção, porque um logger que derruba a aplicação por causa de um problema de logging é pior do que um que descarta eventos.

Vale a pena saber desse silêncio. SelfLog é o canal de diagnóstico do próprio Serilog, e direcioná-lo para o console é a forma mais rápida de descobrir por que um arquivo nunca apareceu.

Quais opções de rotação configurar?

Três, e elas funcionam juntas: um intervalo, um limite de tamanho com a rotação ativada e um limite de arquivos retidos.

O intervalo facilita a navegação pelos arquivos: com um arquivo por dia, encontrar o log de ontem é só questão de ler o nome do arquivo. O limite de tamanho impede que um único dia movimentado gere um arquivo grande demais para abrir. O limite de arquivos retidos impede que a pasta cresça para sempre.

A armadilha é definir o limite de tamanho sem rollOnFileSizeLimit: true. O sink respeita o limite parando de gravar, e não fazendo a rotação, então o logging termina silenciosamente em algum ponto do dia, sem nenhum erro em lugar nenhum.

Em ambientes regulados, vale a pena pensar com cuidado na retenção. retainedFileCountLimit exclui por quantidade, o que significa que uma semana tranquila e uma semana movimentada retêm volumes diferentes de histórico. retainedFileTimeLimit exclui por idade, o que corresponde ao modo como uma política de retenção costuma ser redigida. Quando os dois estão definidos, prevalece o mais restritivo.

A saída compactada não está nessa lista. O sink de arquivo não tem um parâmetro próprio de gzip; em vez disso, expõe um parâmetro hooks, e uma implementação de FileLifecycleHooks pode envolver o stream de saída no método OnFileOpened para compactar os eventos à medida que são gravados.

Conclusão

Neste artigo, vimos como configurar o logging em arquivos com rotação usando Serilog.Sinks.File. Ao aplicar políticas de rotação como FileSizeLimitBytes e RetainedFileCountLimit, podemos gerenciar os arquivos de log com eficiência e garantir que eles não fiquem grandes demais nem poluam o sistema de arquivos. Com o Serilog, podemos lidar com os arquivos de log de uma aplicação .NET de forma flexível e eficiente.

A quantidade de eventos que chega a esses arquivos, para começo de conversa, é outra alavanca, e vale a pena acioná-la antes de mexer no limite de arquivos retidos: veja os níveis de log do Serilog e o controle do nível mínimo. Quando o volume estiver certo, registrar o nome da classe e do método é o que torna um arquivo grande pesquisável.

Lembre-se de ajustar as políticas de rotação de acordo com as necessidades de logging da aplicação e as limitações de espaço em disco.

Testado com o .NET 10.0.10.