Como criar um ficheiro de log rotativo em PowerShell: passo a passo

Este tutorial mostra como criar um sistema simples de log rotativo em PowerShell para registar mensagens de aplicação ou scripts, útil para evitar ficheiros de log enormes e manter um historial por número ou por tamanho. Explica o porquê e dá um exemplo prático de rotação por tamanho com backups numerados.

Pré-requisitos

• Windows com PowerShell 5.1+ ou PowerShell 7+
• Permissão de escrita na pasta onde os logs serão guardados
• Editor de texto para criar o script (ex.: Notepad, VS Code)

Passo 1: decidir a estratégia de rotação

Antes de codificar, escolha se a rotação será por tamanho, por data ou por número de entradas. Neste exemplo implementamos rotação por tamanho com um número fixo de cópias (ex.: mantemos 5 backups). A lógica é: quando o ficheiro principal excede o limite, renomear para .1, deslocar .1 para .2, etc., e criar um novo ficheiro.

Passo 2: criar funções básicas de escrita de log

Crie uma função simples que escreve entradas com timestamp. Isto separa a escrita da lógica de rotação e facilita testes.

function Write-LogEntry {
    param(
        [string]$Message,
        [string]$LogPath = "C:\Logs\app.log"
    )
    $time = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
    "$time - $Message" | Out-File -FilePath $LogPath -Encoding UTF8 -Append
}

Passo 3: implementar a função de rotação por tamanho

A função verifica o tamanho do ficheiro e, se exceder o limite, roda os ficheiros existentes até ao máximo definido. Usamos manipulação de ficheiros com Test-Path, Get-Item e Move-Item.

function Rotate-LogIfNeeded {
    param(
        [string]$LogPath = "C:\Logs\app.log",
        [int]$MaxBytes = 1048576,    # 1 MB
        [int]$MaxBackups = 5
    )

    if (-not (Test-Path $LogPath)) { return }

    $size = (Get-Item $LogPath).Length
    if ($size -lt $MaxBytes) { return }

    # Remover o backup mais antigo se existir
    $oldest = "$LogPath.$MaxBackups"
    if (Test-Path $oldest) { Remove-Item -Path $oldest -Force }

    # Deslocar backups (ex.: app.log.4 -> app.log.5)
    for ($i = $MaxBackups - 1; $i -ge 1; $i--) {
        $src = "$LogPath.$i"
        $dst = "$LogPath." + ($i + 1)
        if (Test-Path $src) { Move-Item -Path $src -Destination $dst -Force }
    }

    # Renomear o ficheiro actual para .1
    Move-Item -Path $LogPath -Destination "$LogPath.1" -Force

    # Opcional: criar novo ficheiro vazio
    "" | Out-File -FilePath $LogPath -Encoding UTF8
}

Passo 4: combinar rotação com escrita (exemplo de uso)

Chame Rotate-LogIfNeeded antes de escrever uma nova entrada. Assim garante que a entrada inicial do ficheiro novo ficará no ficheiro vazio criado.

# Exemplo de uso simples
$log = 'C:\Logs\app.log'
$maxBytes = 500000   # 500 KB
$maxBackups = 3

# Garantir que a pasta existe
$dir = Split-Path $log
if (-not (Test-Path $dir)) { New-Item -Path $dir -ItemType Directory | Out-Null }

# Rotacionar se necessário e escrever várias entradas
Rotate-LogIfNeeded -LogPath $log -MaxBytes $maxBytes -MaxBackups $maxBackups
Write-LogEntry -Message 'Aplicação iniciada' -LogPath $log
Write-LogEntry -Message 'Evento de teste' -LogPath $log

Passo 5: integração com scripts existentes e agendamento

Para integrar, importe as funções no início dos seus scripts e chame Rotate-LogIfNeeded antes de Write-LogEntry. Para execução periódica utilize o Task Scheduler ou agende pelo seu sistema de execução (ex.: correr o script principal que escreve logs).

Verificar o resultado

Abra a pasta de logs e verifique se existe app.log e ficheiros app.log.1, app.log.2, etc., até ao número de backups. Confirme que app.log contém as entradas mais recentes e que os ficheiros numerados contêm entradas anteriores. Verifique tamanhos com Get-ChildItem -Path C:\Logs | Select Name, Length.

Conclusão

Com estas funções tem um sistema simples de log rotativo em PowerShell que evita ficheiros demasiado grandes e mantém um historial limitado. Próximos passos: adaptar a rotação por data, comprimir backups (Compress-Archive) ou enviar logs para um SIEM. Dica: teste sempre com limites baixos para validar a rotação antes de usar em produção — precisa de ajuda para adicionar compressão automática?