Registro de logs em aplicações PHP: melhores práticas e ferramentas

Introdução: Por que o logging é a base de uma aplicação PHP confiável

Logging (log) é o processo de registrar eventos que ocorrem em uma aplicação em um diário especial (arquivo de log). Para um desenvolvedor PHP, um logging adequado não é apenas um "plus na karma", mas uma necessidade. Sem ele, depurar erros de produção se torna um jogo de adivinhação, e o monitoramento de desempenho se torna impossível. Um logging mal configurado pode levar ao vazamento de dados sensíveis ou, ao contrário, à perda de informações criticamente importantes.

Neste artigo, vamos abordar as melhores práticas de logging em PHP: desde a escolha da biblioteca e níveis de logging até a estruturação de mensagens e segurança. Você aprenderá como transformar echo e var_dump dispersos em um sistema profissional de monitoramento.

1. Escolha da biblioteca: PSR-3 e Monolog

Na comunidade PHP moderna, o padrão de facto é a interface Psr\\Log\\LoggerInterface (PSR-3). Ela define 8 métodos para diferentes níveis de logging: emergency, alert, critical, error, warning, notice, info, debug.

A implementação mais popular do PSR-3 é a biblioteca Monolog. Ela é flexível, poderosa e suportada por praticamente todos os frameworks modernos (Laravel, Symfony, Yii2).

Instalação do Monolog via Composer

composer require monolog/monolog

Exemplo básico de uso

<?phprequire 'vendor/autoload.php';

use Monolog\\Logger;use Monolog\\Handler\\StreamHandler;

// Criamos um logger com nome de canal (por exemplo, 'my_app')$log = new Logger('my_app');// Adicionamos um handler: escrevemos em arquivo, nível - INFO e acima$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Logger::INFO));

// Registramos mensagens$log->info('Usuário fez login no sistema', ['user_id' => 123]);$log->warning('Senha incorreta', ['attempts' => 3]);$log->error('Erro de conexão com o banco de dados', ['exception' => $e->getMessage()]);?>

Observe: o segundo argumento é o contexto (context). Nele, você pode passar quaisquer dados adicionais: ID do usuário, IP, stack trace, etc. Nunca concatene dados na string da mensagem — use o contexto.

2. Níveis de logging e filtragem

Usar os níveis corretos é a base de um log legível. A regra geral: quanto maior o nível, menos mensagens. Aqui está uma breve folha de dicas:

• DEBUG (100) — informações de depuração para desenvolvimento. Em produção, geralmente desativado.
• INFO (200) — eventos importantes: usuário registrado, pedido criado.
• NOTICE (250) — eventos normais, mas significativos.
• WARNING (300) — situação anormal, mas a aplicação continua funcionando (por exemplo, tentativa de login malsucedida).
• ERROR (400) — erro que requer intervenção (não foi possível salvar o arquivo).
• CRITICAL (500) — erro crítico (banco de dados indisponível).
• ALERT (550) — ação imediata necessária.
• EMERGENCY (600) — sistema inoperável.

Filtragem em diferentes ambientes

Em produção, não é necessário escrever mensagens DEBUG — elas criam carga extra no disco e dificultam a busca por registros importantes. Use handlers diferentes para ambientes diferentes:

<?phpuse Monolog\\Logger;use Monolog\\Handler\\StreamHandler;use Monolog\\Handler\\FingersCrossedHandler;

$log = new Logger('app');

if (getenv('APP_ENV') === 'production') {    // Em produção, escrevemos apenas WARNING e acima    $log->pushHandler(new StreamHandler('/var/log/app/error.log', Logger::WARNING));    // FingersCrossedHandler: armazena em buffer tudo, mas só escreve em caso de erro    $log->pushHandler(new FingersCrossedHandler(        new StreamHandle
```