finatto/telemetry

Wide-event telemetry dispatcher for Laravel 13 applications.

dev-master 2026-05-06 00:15 UTC

Requires

• php: ^8.3
• illuminate/http: ^13.0
• illuminate/queue: ^13.0
• illuminate/support: ^13.0
• ramsey/uuid: ^4.7

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/framework: ^13.0
• orchestra/testbench: ^11.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/phpstan: ^2.0

MIT

README

Wide-event telemetry para aplicações Laravel. Captura um evento por request via middleware, despacha para uma fila Redis dedicada, e um worker envia em batch para a API de logging.

• Um wide event por request. Sem Log::info() espalhados.
• Contexto, não strings. Campos nomeados.
• Tail sampling. 5xx e exceptions sempre. Sucesso por amostragem.
• Falha silenciosa. Telemetria nunca derruba a aplicação.

Instalação

composer require finatto/telemetry
php artisan vendor:publish --tag=telemetry-config

Auto-discovery registra o TelemetryServiceProvider e a Facade Telemetry automaticamente.

Configuração mínima (.env)

TELEMETRY_SERVICE_NAME=finatto-admin
TELEMETRY_API_URL=http://telemetry-api:8080
TELEMETRY_API_KEY=sua-api-key
TELEMETRY_SAMPLE_RATE=0.1

Registrar middleware (bootstrap/app.php)

use Finatto\Telemetry\WideEventContext;
use Finatto\Telemetry\WideEventMiddleware;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->api(append: [WideEventMiddleware::class]);
    $middleware->web(append: [WideEventMiddleware::class]);
})
->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (\Throwable $e): void {
        app(WideEventContext::class)->markException($e);
    });
})

Queue connection dedicada (config/queue.php)

'connections' => [
    'telemetry-redis' => [
        'driver'      => 'redis',
        'connection'  => 'default',
        'queue'       => env('TELEMETRY_QUEUE_NAME', 'telemetry'),
        'retry_after' => 30,
    ],
],

E rode um worker isolado:

php artisan queue:work telemetry-redis --queue=telemetry

Adicionando contexto de negócio

Em qualquer ponto do ciclo da request:

use Finatto\Telemetry\Facades\Telemetry;

Telemetry::enrich([
    'tenant_id' => $tenant->id,
    'module'    => 'fleet',
    'plan'      => $tenant->plan,
]);

Os campos são mesclados recursivamente no payload e despachados no terminate() do middleware.

Exemplo de evento gerado

{
  "event_id": "01925f3a-7c2d-...",
  "service": "finatto-admin",
  "environment": "production",
  "version": "1.4.2",
  "timestamp": "2026-05-04T14:22:31.847291Z",
  "payload": {
    "http":     { "method": "POST", "path": "/api/modules", "status_code": 201, "duration_ms": 138 },
    "auth":     { "user_id": "usr_456" },
    "business": { "tenant_id": "ten_789", "module": "fleet", "plan": "pro" }
  }
}

Sanitização

PayloadSanitizer redige automaticamente chaves contendo qualquer substring de: password, secret, token, authorization, credit_card, api_key (case-insensitive, recursivo).

Testes

composer install
vendor/bin/pest
vendor/bin/phpstan analyse

Licença

MIT