README

Um pacote Laravel projetado para capturar exceções (tratadas e não tratadas), interceptar requisições HTTP, monitorar queries de banco, comandos Artisan e operações de cache, enviando tudo de forma assíncrona (em lotes) para a AWS SQS sem bloquear o tempo de resposta da aplicação principal.

Compatível com PHP 7.2+ e Laravel 6 até 11.

Compatibilidade

Laravel	PHP	Suporte
6.x	7.2+	✅ (sem HTTP Client timeline)
7.x	7.2+	✅
8.x	7.3+	✅
9.x	8.0+	✅
10.x	8.1+	✅
11.x	8.2+	✅

Nota: No Laravel 6, os listeners de HTTP Client (ResponseReceived, ConnectionFailed) não serão registrados, pois o HTTP Client foi introduzido no Laravel 7. Todas as demais funcionalidades (queries, cache, commands, exceptions) funcionam normalmente.

Por que usar este SDK?

O PHP rodando no modelo tradicional FPM "morre" (é encerrado) ao final de cada requisição. Registros síncronos em serviços externos (como AWS) afetam diretamente o tempo de resposta para o usuário final, deixando a aplicação mais lenta.

Este SDK resolve esse problema usando um Buffer (Singleton) em Memória. As telemetrias capturadas (Requisições, Exceções, Queries, Commands, Cache) são armazenadas temporariamente em um array na memória da aplicação durante o processamento da requisição.

Somente depois que o Servidor Web envia a resposta de volta ao navegador do cliente (via FastCGI), o Laravel dispara o gancho do ciclo de vida chamado app()->terminating(). Este SDK registra um listener (ouvinte) exatamente nesse ponto para:

Recolher o array de itens armazenados na memória.
Agrupar em lotes (uma vez que a API da AWS SQS possui um limite de 10 mensagens por lote).
Executar o envio (I/O de rede) em background, de modo totalmente não bloqueante para a experiência do usuário.

Para aplicações executadas via Laravel Octane, este SDK é totalmente seguro: O buffer é forçosamente limpo sempre que as mensagens são enviadas, prevenindo memory leaks (vazamento de memória) entre as requisições.

Instalação

composer require pablocarvalho/laravel-sqs-telemetry

Ou, para usar via path repository localmente:

"repositories": [
    {
        "type": "path",
        "url": "../laravel-sqs-telemetry"
    }
],

Configuração

Publique o arquivo de configuração e prepare suas variáveis de ambiente:

php artisan vendor:publish --tag=sqs-telemetry-config

Em seguida, adicione as variáveis necessárias ao seu arquivo .env:

SQS_TELEMETRY_ENABLED=true
SQS_TELEMETRY_QUEUE_URL="https://sqs.us-east-1.amazonaws.com/123456789012/my-telemetry-queue"
AWS_ACCESS_KEY_ID="your-key"
AWS_SECRET_ACCESS_KEY="your-secret"
AWS_DEFAULT_REGION="us-east-1"
SQS_TELEMETRY_BATCH_SIZE=10

# AI Configs (Opcional - Requer OpenAI Key)
SQS_TELEMETRY_AI_ENABLED=true
SQS_TELEMETRY_AI_API_KEY="sk-..."

Uso

1. Rastreamento de Requisições HTTP (Middleware)

Adicione o middleware no seu HTTP Kernel ou grupo de Rotas.

Laravel 6 até 10 — No arquivo app/Http/Kernel.php:

protected $middlewareGroups = [
    'web' => [
        // ...
        \Pablocarvalho\SqsTelemetry\Middleware\SqsTelemetryBufferMiddleware::class,
    ],
    'api' => [
        // ...
        \Pablocarvalho\SqsTelemetry\Middleware\SqsTelemetryBufferMiddleware::class,
    ],
];

Laravel 11 — No arquivo bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Pablocarvalho\SqsTelemetry\Middleware\SqsTelemetryBufferMiddleware::class);
})

2. Rastreamento de Exceções

Registre no Handler principal para que as exceções não tratadas sejam absorvidas pelo buffer.

Laravel 6 e 7 — No arquivo app/Exceptions/Handler.php, método report():

public function report(Throwable $exception)
{
    app(\Pablocarvalho\SqsTelemetry\Handlers\SqsExceptionHandler::class)->report($exception);
    parent::report($exception);
}

Laravel 8 até 10 — No arquivo app/Exceptions/Handler.php, método register():

public function register(): void
{
    $this->reportable(function (\Throwable $e) {
        app(\Pablocarvalho\SqsTelemetry\Handlers\SqsExceptionHandler::class)->report($e);
    });
}

Laravel 11 — No arquivo bootstrap/app.php:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (\Throwable $e) {
        app(\Pablocarvalho\SqsTelemetry\Handlers\SqsExceptionHandler::class)->report($e);
    });
})

Exceptions tratadas (catch): A partir da v1.0.7, exceptions logadas via report($e) ou Log::error('msg', ['exception' => $e]) são capturadas automaticamente pelo listener MessageLogged, sem necessidade de configuração adicional.

O que é capturado?

Request (Middleware)

url, method, ip, user_agent
status_code, execution_time (em ms)
timestamp, headers, payload (senhas e tokens são substituídos por ********)
timeline — eventos detalhados do ciclo de vida da request

Exceptions (Handler + MessageLogged)

class, message, file, line
url (se via HTTP), method
timestamp, headers, payload
stack_trace (limitado a 10 linhas)
handled — true se a exception foi tratada em um catch
log_level — nível do log (error, warning, etc.)
ai_resolution_report (se o módulo de IA estiver ativado)

Commands (Artisan)

command, exit_code
execution_time (em ms)
timestamp, timeline

Timeline (automático)

Cada request/command captura um timeline detalhado com:

Evento	Descrição
`db_query`	Queries SQL com tempo de execução, connection, database e bindings (com sanitização automática de dados sensíveis)
`http_request`	Chamadas HTTP externas (Laravel 7+)
`cache_hit` / `cache_miss` / `cache_write` / `cache_forget`	Operações de cache
`exception`	Exceptions capturadas durante a execução
`command_start` / `command_finished`	Início e fim de comandos Artisan

Sanitização de Bindings

Campos sensíveis são automaticamente substituídos por [REDACTED]:

password, secret, token, api_key, cpf, cnpj

Exemplo de evento db_query no timeline:

{
    "type": "db_query",
    "description": "insert into \"users\" (\"name\", \"email\", \"password\") values (?, ?, ?)",
    "duration_ms": 2.0,
    "context": {
        "connection": "pgsql",
        "database": "meu_banco",
        "bindings": ["John", "john@example.com", "[REDACTED]"]
    }
}

Análise de Exceções por Inteligência Artificial

A aplicação integra a API da OpenAI para gerar resoluções detalhadas (Code Scan e context injection). Se você habilitar, a varredura buscará a linha exata no seu código local (app/, etc.) de onde o stacktrace alertou o erro, obtendo linhas de antes e de depois, enviando as para a IA e gerando orientações em Markdown para facilitar a resolução dentro do seu Client / Relatórios.

Aviso: Processar via IA adicionará um tempo extra (~1-5 segundos) para a exceção ser consolidada e enviada via SQS.

Configurações do Timeline

Todas as opções de timeline podem ser configuradas no arquivo config/sqs-telemetry.php:

'timeline' => [
    'db'          => env('SQS_TELEMETRY_TIMELINE_DB', true),
    'db_bindings' => true, // sempre ativo, com sanitização automática
    'http'        => env('SQS_TELEMETRY_TIMELINE_HTTP', true),
    'cache'       => env('SQS_TELEMETRY_TIMELINE_CACHE', true),
    'commands'    => env('SQS_TELEMETRY_TIMELINE_COMMANDS', true),
    'exceptions'  => env('SQS_TELEMETRY_TIMELINE_EXCEPTIONS', true),
],

pablocarvalho / laravel-sqs-telemetry

Maintainers

Package info

Statistics

Security