README

Package privé d’observabilité applicative pour Laravel 11, 12 et 13. Il collecte sans interrompre l’application hôte les requêtes HTTP, logs, jobs de queue et métriques métier, puis les envoie par lots à Data Hub.

Installation

Configurez le dépôt Composer privé de votre organisation, puis installez le package :

composer require mltstephane/data-hub
php artisan vendor:publish --tag=data-hub-config

Le provider, le middleware HTTP, les listeners et la façade Metrics sont auto-découverts. Aucune modification de bootstrap/app.php ou config/logging.php n’est nécessaire.

Configuration minimale

Créez une clé depuis la page dédiée de votre projet Data Hub et conservez-la dans le gestionnaire de secrets de l’application :

DATA_HUB_ENABLED=true
DATA_HUB_URL=https://data-hub.example.com
DATA_HUB_API_KEY=hub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DATA_HUB_PROJECT=boutique
DATA_HUB_ENVIRONMENT=production
DATA_HUB_HOST=web-01

En production, DATA_HUB_URL doit utiliser HTTPS. L’URL peut être la racine Data Hub ou l’endpoint complet /api/v1/batch.

Métriques métier

use Metrics;

Metrics::count('orders.created', tags: ['channel' => 'web']);
Metrics::gauge('queue.depth', 42, ['queue' => 'emails']);
Metrics::timing('checkout.duration', 185.4, ['payment' => 'card']);

Les événements de jobs incluent leur numéro de tentative. Les retries d’un même job restent donc des exécutions distinctes côté Data Hub. Les jobs internes de flush du package sont exclus de la capture.

Buffer durable et envoi

Avec un cache Redis, le package sélectionne automatiquement un backend de liste Redis avec ajout, lecture et acquittement atomiques O(1). Avec les autres stores Laravel, il conserve un mode de compatibilité borné fondé sur un tableau cache et un verrou ; ce mode réécrit le tableau et convient surtout aux volumes modérés. Le backend actif apparaît dans la sortie de data-hub:flush.

Cette durabilité est bornée, pas sans perte : lorsque la capacité est atteinte, la politique d’overflow configurée supprime explicitement l’entrée la plus ancienne ou refuse la plus récente. Les compteurs diagnostiques rendent ces pertes observables. Les entrées JSON irréparablement invalides sont mises en quarantaine individuellement afin de ne jamais bloquer la tête FIFO.

Un seul flush est mis en queue lors du franchissement du seuil grâce à un marqueur cache atomique. Si la connexion choisie est sync, aucun flush de seuil et aucun appel HTTP synchrone ne sont déclenchés ; la commande planifiée ou manuelle envoie le reliquat.

DATA_HUB_BUFFER_SIZE=1000
DATA_HUB_CHUNK_SIZE=100
DATA_HUB_FLUSH_THRESHOLD=50
DATA_HUB_OVERFLOW_POLICY=drop_oldest
DATA_HUB_CACHE_STORE=redis
# Facultatif : une valeur vide dérive un namespace isolé de l’endpoint, de la clé et du projet.
DATA_HUB_CACHE_KEY=
DATA_HUB_BUFFER_LOCK_SECONDS=5
DATA_HUB_BUFFER_LOCK_WAIT_SECONDS=1
DATA_HUB_FLUSH_LOCK_SECONDS=0
DATA_HUB_QUEUE_CONNECTION=redis
DATA_HUB_QUEUE=default
DATA_HUB_CONNECT_TIMEOUT=3
DATA_HUB_REQUEST_TIMEOUT=10
DATA_HUB_RETRIES=2

Politiques disponibles : drop_oldest (défaut) et drop_newest. php artisan data-hub:flush affiche la taille du buffer ainsi que les compteurs overflow, quarantined, invalid_metric, write_lock_failures, backend_failures et dispatch_failures.

Les métriques sont arrondies à six décimales avant mise en buffer afin de respecter DECIMAL(20,6). Les valeurs non finies ou hors de la plage ±99 999 999 999 999,999999 sont ignorées sans interrompre l’application et incrémentent invalid_metric.

Les acquittements retirent uniquement les enregistrements de stockage effectivement envoyés, chacun possédant un ID interne distinct de l’ID d’idempotence API. Un flusher expiré peut donc renvoyer un événement — l’API est idempotente — mais ne peut jamais supprimer une entrée ajoutée ou non envoyée après son snapshot. Les clés Lua partagent un hash-tag Redis Cluster. La durée du verrou de flush est dérivée du budget HTTP et de la capacité du buffer lorsque DATA_HUB_FLUSH_LOCK_SECONDS=0.

Sans DATA_HUB_CACHE_KEY, le namespace effectif est dérivé par hash de l’endpoint normalisé, de l’identifiant hashé de la clé, du nom de l’application, de l’environnement et du projet. La clé API brute n’apparaît jamais dans les clés cache.

Envoi manuel :

php artisan data-hub:flush

Capture et confidentialité

DATA_HUB_MIN_LEVEL=warning
DATA_HUB_CAPTURE_REQUESTS=true
DATA_HUB_CAPTURE_LOGS=true
DATA_HUB_CAPTURE_JOBS=true
DATA_HUB_CAPTURE_EXCEPTION_TRACE=false
DATA_HUB_CAPTURE_IP=false
DATA_HUB_CAPTURE_USER_AGENT=false
DATA_HUB_EXCEPT_PATHS=up,telescope/*,horizon/*
DATA_HUB_REDACTION_KEYS=password,token,authorization,cookie,secret,api_key
DATA_HUB_MAX_STRING_LENGTH=10000

Les clés sensibles sont canonicalisées et masquées récursivement dans les contextes, en-têtes et cookies. Les secrets intégrés aux messages et URL sont également retirés. Les traces d’exception sont désactivées par défaut ; si elles sont explicitement activées, elles sont nettoyées et tronquées. L’endpoint Data Hub effectif et les chemins exclus ne sont jamais capturés, ce qui évite les boucles. Les captures restent fail-open, mais les flushs queue/manuels utilisent des lectures strictes : une panne conserve le marqueur pending et provoque un retry ou un code de sortie non nul.

Tests

composer install
vendor/bin/phpunit

Ce package est privé et distribué sous licence propriétaire.

mltstephane / data-hub

Maintainers

Package info

Statistics

Security