PHPackages                             pablocarvalho/laravel-sqs-telemetry - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. pablocarvalho/laravel-sqs-telemetry

ActiveLibrary[Queues & Workers](/categories/queues)

pablocarvalho/laravel-sqs-telemetry
===================================

A Laravel SDK for sending exception and request telemetry to AWS SQS asynchronously with batching and memory buffer.

v1.1.4(1mo ago)0245↑291.8%MITPHPPHP ^7.2 || ^7.3 || ^7.4 || ^8.0 || ^8.1 || ^8.2 || ^8.3

Since Mar 12Pushed 1mo agoCompare

[ Source](https://github.com/pablo-carvalho-thinksystems/laravel-sqs-telemetry)[ Packagist](https://packagist.org/packages/pablocarvalho/laravel-sqs-telemetry)[ RSS](/packages/pablocarvalho-laravel-sqs-telemetry/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (6)Versions (15)Used By (0)

Laravel SQS Telemetry SDK
=========================

[](#laravel-sqs-telemetry-sdk)

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
---------------

[](#compatibilidade)

LaravelPHPSuporte6.x7.2+✅ (sem HTTP Client timeline)7.x7.2+✅8.x7.3+✅9.x8.0+✅10.x8.1+✅11.x8.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?
----------------------

[](#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:

1. Recolher o array de itens armazenados na memória.
2. Agrupar em lotes (uma vez que a API da AWS SQS possui um limite de 10 mensagens por lote).
3. 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
----------

[](#instalação)

```
composer require pablocarvalho/laravel-sqs-telemetry
```

Ou, para usar via *path repository* localmente:

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

Configuração
------------

[](#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
---

[](#uso)

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

[](#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

[](#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?
------------------

[](#o-que-é-capturado)

### Request (Middleware)

[](#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)

[](#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)

[](#commands-artisan)

- `command`, `exit_code`
- `execution_time` (em ms)
- `timestamp`, `timeline`

### Timeline (automático)

[](#timeline-automático)

Cada request/command captura um timeline detalhado com:

EventoDescriçã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

[](#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
-----------------------------------------------

[](#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
-------------------------

[](#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),
],
```

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance89

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

14

Last Release

54d ago

PHP version history (3 changes)v1.0.0PHP ^7.4 || ^8.0

v1.0.3PHP ^7.3 || ^7.4 || ^8.0 || ^8.1 || ^8.2 || ^8.3

v1.0.6PHP ^7.2 || ^7.3 || ^7.4 || ^8.0 || ^8.1 || ^8.2 || ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/bf8823d0390b975bf7428168f23af34bbcafeefa542dedc505076a41d0a23649?d=identicon)[pablo-carvalho-thinksystems](/maintainers/pablo-carvalho-thinksystems)

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/pablocarvalho-laravel-sqs-telemetry/health.svg)

```
[![Health](https://phpackages.com/badges/pablocarvalho-laravel-sqs-telemetry/health.svg)](https://phpackages.com/packages/pablocarvalho-laravel-sqs-telemetry)
```

###  Alternatives

[bref/laravel-bridge

An advanced Laravel integration for Bref, including Octane support.

3384.1M11](/packages/bref-laravel-bridge)[illuminate/queue

The Illuminate Queue package.

20331.4M1.2k](/packages/illuminate-queue)[illuminate/bus

The Illuminate Bus package.

6043.8M409](/packages/illuminate-bus)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

44643.1k1](/packages/pressbooks-pressbooks)[palpalani/laravel-sqs-queue-json-reader

Custom SQS queue reader for Laravel

26109.8k](/packages/palpalani-laravel-sqs-queue-json-reader)[harris21/laravel-fuse

Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures.

3786.5k](/packages/harris21-laravel-fuse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)