> LOADING LOG-HOLE v2.0...

LogHole

Sistema de logging avancado para Laravel com armazenamento em base de dados, dashboard web, atributos PHP e ferramentas CLI.

Ver no GitHub

Overview

O LogHole e um pacote de logging avancado que funciona como uma ponte entre os eventos da aplicacao e o armazenamento persistente em base de dados. Integra-se nativamente com a infraestrutura de logging do Laravel atraves de um canal Monolog personalizado.

PHP 8.2+ Laravel 10-11 MIT License PSR-3 Compliant Larastan Level 5

Funcionalidades principais

Canal Monolog para base de dados -- armazenamento persistente de logs
Multi-database -- MySQL, MariaDB, PostgreSQL, SQLite, SQL Server
Dashboard web -- interface com Tailwind CSS e Alpine.js
Atributos PHP 8.2+ -- logging declarativo com #[Loggable]
Ferramentas CLI -- comandos Artisan para consulta e gestao
Troca de tema -- preferencias persistentes no dashboard
Arquitetura extensivel -- Strategy pattern para drivers customizados

Instalacao

Instale via Composer, publique a configuracao e execute as migrations.

Instalacao

bash

composer require digitaldev-lx/log-hole

Publicar configuracao e migrar

bash

php artisan vendor:publish --provider="Digitaldev\LogHole\LogHoleServiceProvider" --tag=config
php artisan migrate

Configuracao

Apos a publicacao, o ficheiro de configuracao fica em config/log-hole.php. Aqui pode definir a conexao de base de dados, autorizacao do dashboard, caminhos das rotas, paginacao e intervalos de auto-refresh.

Adicionar o canal de logging

Adicione o canal database ao ficheiro config/logging.php:

config/logging.php

php

'channels' => [
    // ... outros canais

    'database' => [
        'driver' => 'custom',
        'via' => \Digitaldev\LogHole\Logging\DatabaseLogger::class,
        'level' => 'debug',
    ],
],

Autorizacao do dashboard

Restrinja o acesso ao dashboard definindo os emails autorizados no ficheiro de configuracao:

config/log-hole.php

php

'dashboard' => [
    'enabled' => true,
    'path' => 'log-hole',
    'authorized_emails' => [
        'admin@empresa.pt',
        'dev@empresa.pt',
    ],
    'pagination' => 50,
    'auto_refresh' => 30, // segundos
],

Utilizacao

Via Facade do Laravel

Utilize a facade Log standard do Laravel, direcionando para o canal database. Todos os niveis PSR-3 sao suportados.

Logging via Facade

php

use Illuminate\Support\Facades\Log;

// Informacao geral
Log::channel('database')->info('Utilizador autenticou', [
    'user_id' => $user->id,
    'ip' => request()->ip(),
]);

// Erro com contexto detalhado
Log::channel('database')->error('Falha no pagamento', [
    'order_id' => 'ORD-123',
    'error' => 'Fundos insuficientes',
    'gateway' => 'eupago',
]);

// Aviso operacional
Log::channel('database')->warning('Rate limit proximo do maximo', [
    'endpoint' => '/api/v1/users',
    'current_rate' => 95,
    'max_rate' => 100,
]);

// Debug para troubleshooting
Log::channel('database')->debug('Query lenta detetada', [
    'query' => $sql,
    'time_ms' => 1250,
    'table' => 'orders',
]);

Logging com atributos PHP

O atributo #[Loggable] permite logging declarativo. Aplique-o a nivel de classe (afeta todos os metodos) ou a nivel de metodo (override das definicoes da classe).

Atributo #[Loggable]

php

use Digitaldev\LogHole\Attributes\Loggable;

// Aplica a todos os metodos do controller
#[Loggable(message: 'Acao de pagamento executada', level: 'info')]
class PaymentController extends Controller
{
    // Override: log com nivel warning e contexto do request
    #[Loggable(
        message: 'A processar reembolso',
        level: 'warning',
        withRequest: true
    )]
    public function refund(Request $request)
    {
        // O LogHole regista automaticamente esta acao
        // incluindo dados do request (headers, body, query)
    }

    // Usa as definicoes da classe (info level)
    public function index()
    {
        // Registado automaticamente com a mensagem da classe
    }
}

Parametros do atributo

Parametro	Tipo	Descricao
message	string	Mensagem personalizada para o log
level	string	Nivel PSR-3 (debug, info, warning, error, etc.)
withRequest	bool	Incluir dados do HTTP request no contexto
channel	string\|null	Canal de destino (default: database)

Dashboard Web

O LogHole inclui um dashboard web completo, acessivel na rota configurada (por defeito /log-hole). Construido com Tailwind CSS e Alpine.js, oferece uma interface rica para monitorizar e filtrar logs.

Funcionalidades do dashboard

Estatisticas por nivel -- contagem de logs por nivel (info, warning, error, etc.)
Filtragem server-side -- filtrar por nivel, conteudo e intervalo de datas
Contexto expandivel -- visualizacao JSON formatada do contexto de cada log
Troca de tema -- preferencias de tema persistentes entre sessoes
Auto-refresh -- atualizacao automatica com intervalo configuravel
Controlo de acesso -- restricao por lista de emails autorizados
Paginacao -- navegacao eficiente em grandes volumes de logs

Acesso ao dashboard

O dashboard esta protegido por autenticacao. Apenas utilizadores autenticados cujo email conste na lista authorized_emails da configuracao podem aceder. Isto garante que apenas membros da equipa tecnica consultam os logs da aplicacao.

Ferramentas CLI

O comando log-hole:tail permite consultar e gerir logs directamente no terminal, com output tabular e contexto JSON formatado.

Consultar logs recentes

bash

# Ver ultimos logs
php artisan log-hole:tail

# Filtrar por nivel
php artisan log-hole:tail --level=error

# Filtrar por intervalo de datas
php artisan log-hole:tail --from="2024-01-01" --to="2024-01-31"

# Limitar numero de resultados
php artisan log-hole:tail --limit=50

Limpeza de logs antigos

Remova logs antigos em massa para manter a base de dados limpa:

Purgar logs

bash

# Remover logs com mais de 30 dias
php artisan log-hole:tail --purge --days=30

# Remover logs com mais de 90 dias
php artisan log-hole:tail --purge --days=90

Opcoes disponiveis

Opcao	Descricao
--level	Filtrar por nivel (debug, info, warning, error, critical, alert, emergency)
--from	Data inicial (formato YYYY-MM-DD)
--to	Data final (formato YYYY-MM-DD)
--limit	Numero maximo de resultados
--purge --days=N	Remover logs com mais de N dias

Boas Praticas

Usar contexto estruturado

Passe sempre um array de contexto com dados relevantes. Contexto estruturado facilita a filtragem e analise no dashboard. Evite mensagens genericas como "Erro ocorreu" -- inclua IDs, nomes de operacao e dados que ajudem no debug.

Escolher o nivel correto

Use debug para troubleshooting, info para eventos normais, warning para situacoes anomalas mas recuperaveis, e error para falhas que requerem atencao.

Configurar rotacao de logs

Agende o comando de purge no scheduler do Laravel para evitar que a tabela de logs cresca indefinidamente. Uma retencao de 30-90 dias e tipicamente suficiente para a maioria dos cenarios.

routes/console.php - Agendar purge

php

Schedule::command('log-hole:tail --purge --days=30')
    ->daily()
    ->at('03:00');

Proteger o dashboard

Mantenha a lista de emails autorizados atualizada e use sempre HTTPS em producao. O dashboard mostra informacao sensivel -- trate-o como uma ferramenta interna.

Nao logar dados sensiveis

Nunca inclua passwords, tokens, numeros de cartao de credito ou dados pessoais identificaveis no contexto dos logs. Mascare ou omita informacao sensivel.

Combinar com o stack channel

Use o canal stack do Laravel para enviar logs simultaneamente para ficheiro e base de dados, garantindo redundancia.

config/logging.php - Stack channel

php

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['daily', 'database'],
    ],
],

$ composer require digitaldev-lx/log-hole

Logging que funciona para si

Consulte o repositorio no GitHub para a documentacao completa, issues e contribuicoes.

Ver no GitHub ← Todos os Packages