Monitoramento e registro de logs de aplicações PHP: como não perder um erro

Sua aplicação PHP não fala, ela grita

Imagine que você é o capitão de uma nave espacial. Sua missão é chegar a Marte. Mas a nave não tem instrumentos, nem sensores, e nem mesmo um botão de "alarme de emergência". Você simplesmente voa, torcendo pelo melhor. É mais ou menos assim que se sente um desenvolvedor que coloca uma aplicação PHP em produção sem monitoramento e registro de logs.

Os usuários veem "500 Internal Server Error", e você vê apenas uma tela vazia de logs. Familiar? Se não, ou você é um gênio, ou simplesmente ainda não enfrentou a queda de um servidor em produção às 3 da manhã.

Neste artigo, vamos explorar como transformar sua aplicação PHP de uma "caixa preta" em um sistema transparente que conta exatamente onde e por que falhou. Mostrarei código real, melhores práticas e ferramentas usadas em produção por grandes projetos. Vamos nessa.

Por que registrar logs em PHP não é apenas "echo"

Muitos iniciantes pensam que registrar logs é:

echo "Erro aqui: " . $error;

Spoiler: isso não funciona em produção. O usuário verá essa "beleza" na tela. E se o erro for fatal, você nem ficará sabendo.

O verdadeiro registro de logs é a coleta estruturada de dados que podem ser analisados, pesquisados e que geram respostas em tempo real. O PHP oferece funções básicas (error_log(), syslog()), mas no mundo moderno isso não é suficiente.

O que um bom log deve conter?

\n
• Nível de gravidade — DEBUG, INFO, WARNING, ERROR, CRITICAL
\n
• Carimbo de data/hora — hora exata do evento (de preferência em UTC)
\n
• Contexto — ID do usuário, IP, URL, dados da requisição
\n
• Pilha de chamadas — trace do erro
\n
• Identificador único da requisição — para vincular todos os logs de uma mesma ação
\n

Monolog — o padrão de registro de logs em PHP

Se você programa em PHP e não usa Monolog — está perdendo tempo. É o padrão de facto para registro de logs, suportado pelo Symfony, Laravel e pela maioria dos frameworks modernos.

Por que o Monolog é tão bom?

\n
• "Handlers" flexíveis — pode escrever em arquivo, BD, Telegram, Slack, email
\n
• Formatadores — JSON, HTML, Syslog
\n
• Processadores — adicionam contexto automaticamente
\n

Instalação e exemplo básico

composer require monolog/monolog

Agora vamos escrever um logger simples:

<?php\nrequire 'vendor/autoload.php';\n\nuse Monolog\\Logger;\nuse Monolog\\Handler\\StreamHandler;\nuse Monolog\\Handler\\TelegramBotHandler;\nuse Monolog\\Level;\n\n// Cria o logger com o nome do canal\n$log = new Logger('my_app');\n\n// Escreve em arquivo\n$log->pushHandler(\n    new StreamHandler(__DIR__ . '/logs/app.log', Level::Debug)\n);\n\n// Erros críticos — no Telegram\n$log->pushHandler(\n    new TelegramBotHandler(\n        'YOUR_BOT_TOKEN',\n        'YOUR_CHAT_ID',\n        Level::Critical\n    )\n);\n\n// Uso\n$log->info('Usuário fez login', ['user_id' => 123]);\n$log->error('Banco de dados indisponível', ['db_host' => 'localhost']);

Observe: usamos handlers diferentes para níveis diferentes. No arquivo, escrevemos tudo (depuração); no Telegram, apenas o crítico. Isso evita spam de notificações, mas garante que você não perca um problema real.

Monitoramento PHP: como enxergar o que está oculto

Registrar logs é a coleta passiva de dados. Monitoramento é a observação ativa e a notificação. Se o usuário reporta um erro a você — você já chegou atrasado. Um bom monitoramento avisa antes que o problema afete os usuários.

Sentry — item obrigatório para o desenvolvedor PHP

Sentry é um sistema de rastreamento de erros em tempo real. Ele captura exceções, coleta contexto, pilha de chamadas e até dados de sessão.