Rate limiter, scheduler et hooks d'exécution planifiée
Rate limiter, scheduler et hooks d'exécution planifiée
Contrôler le débit, planifier des tâches asynchrones et traiter les commits récents
Documentation des utilitaires permettant de : limiter le débit des opérations de stockage/exécution asynchrone, planifier des hooks/agents et traiter les commits récents. Guide d’utilisation, configuration, exemples pratiques et bonnes pratiques pour éviter les erreurs courantes.
Aperçu des fonctionnalités couvertes
Limitation de débit (rate limiter)
File d’attente et contrôle de la concurrence pour éviter les surcharges et respecter les quotas des fournisseurs ou du moteur d’indexation.
Scheduler / Hooks planifiés
Mécanismes pour exécuter automatiquement des agents / tâches à intervalle régulier (jour, semaine, mois, année) ou à une date précise.
Traitement des commits récents
Flux dédié pour simuler des pushs et ré-exécuter des hooks sur des commits récents (utile pour re-synchronisation, backfill).
Retries et backoff
Retries exponentiels en cas de limites dépassées, avec paramètres ajustables (nombre d’essais, délais, multiplicateur).
Surveillance & progression
Notifications de progression en temps réel (via socket) et stockage local temporaire de l’état des jobs pour reprise après coupure.
Annulation contrôlée
Mécanisme d’annulation des jobs en file ; comportement d’annulation expliqué (limites côté provider).
Public cible
Cette page s’adresse aux personnes qui gèrent l’orchestration des tâches asynchrones (product owners, devops légers, administrateurs d’app). Les explications sont orientées “comment l’utiliser” plutôt que “comment c’est implémenté”.
Workflow : Soumettre une opération asynchrone avec limitation de débit (usage courant)
Étape 1 — Identifier l'opération à protéger
Choisissez l’opération susceptible d’être soumise à un quota ou de générer beaucoup d’appels (ex. : insertion de vecteurs, requêtes vers un service externe, téléchargement/lecture massif de fichiers).
Étape 2 — Décider des contraintes
Déterminez les valeurs cibles : nombre maximum d’appels simultanés (concurrence) et délai minimum entre deux appels. Exemples courants : 3 requêtes simultanées / 200–500 ms d’intervalle.
Étape 3 — Enqueue : soumettre l'opération
Au lieu d’exécuter l’opération immédiatement, placez-la dans la file d’attente du limiteur. La file s’assurera de respecter la concurrence et les délais avant d’exécuter chaque opération.
Étape 4 — Surveiller et recevoir le résultat
La soumission renvoie le résultat quand l’opération est exécutée. Surveillez les logs et la progress bar si disponible ; en cas d’erreur de type “quota”, le mécanisme de retry peut intervenir (voir workflow dédié).
Étape 5 — Ajuster en production
Si vous observez des ralentissements ou des erreurs fréquentes, augmentez le délai minimum entre requêtes ou diminuez la concurrence ; documentez ces changements et observez l’impact.
Commencez conservateur
Commencez avec des paramètres de limite bas (p. ex. 2–3 concurrents, 200–500 ms) et montez progressivement. Cela évite de déclencher des protections chez les fournisseurs externes.
Workflow : Gestion des erreurs et retries avec backoff exponentiel
Étape 1 — Détecter l'erreur rate-limit
Lorsque l’opération échoue avec un indicateur de limite (erreur de quota, HTTP 429, message explicite), considérez-la comme candidate au retry.
Étape 2 — Paramétrer les retries
Choisissez : nombre maximal de tentatives, délai de base (ex. 1s), multiplicateur (p. ex. 2), et délai maximal. Exemple : 3 tentatives, base 1 000 ms, multiplicateur 2, max 10 000 ms.
Étape 3 — Appliquer backoff exponentiel
A chaque tentative échouée, attendez un délai croissant (base * multiplicateur^tentative) jusqu’au délai maximal, puis retentez. Si la dernière tentative échoue, signalez l’erreur et marquez le job comme failed.
Étape 4 — Log et alerting
Consignez les informations d’erreur (types, fréquence) et activez alertes si un même job échoue plusieurs fois, afin d’intervenir manuellement si besoin.
Différenciez erreurs transitoires et permanentes
Ne retentez pas les erreurs clairement permanentes (ex. : entrée invalide) ; limitez les retries aux erreurs indiquant une saturation ou indisponibilité temporaire.
Workflow : Planifier un hook/agent récurrent (création et réglage)
Étape 1 — Choisir le type de trigger
Décidez si le hook doit être déclenché par un événement git (push) ou selon un calendrier (ex. toutes les 2 semaines). Pour les exécutions planifiées, choisissez un intervalle (count + unité : jour/semaine/mois/année) ou une date de prochaine exécution.
Étape 2 — Configurer la fréquence
Indiquez le nombre (p. ex. 1, 7) et la durée (jour, semaine, mois, année). Le système calcule la prochaine date d’exécution en ajoutant ce delta à la date courante ou à la précédente exécution.
Étape 3 — Tester la configuration
Avant de déployer largement, forcez une exécution de test (mode manuel) pour vérifier la sortie, les notifications et l’impact sur les quotas.
Étape 4 — Observer et ajuster
Surveillez la fréquence d’échec et le temps d’exécution. Si une tâche dépasse trop souvent la fenêtre, augmentez l’intervalle ou limitez la charge par exécution (batch smaller).
Étape 5 — Gestion des prochaines exécutions
Après chaque exécution réussie, la prochaine date est recalculée automatiquement selon la fréquence définie. Si une exécution échoue, la prochaine peut être programmée à la fréquence suivante pour éviter enchaînement immédiat d’échecs.
Usage : rapports, résumés réguliers, tâches de maintenance. Bonnes pratiques : garder la charge par exécution faible, tester la logique de calcul de la prochaine exécution, prévoir un fuseau horaire fixe.
Workflow : Traiter des commits récents (re-synchronisation / backfill)
Étape 1 — Définir la fenêtre temporelle et la limite
Choisissez depuis quelle date vous voulez récupérer les commits et le nombre maximal à traiter (p. ex. depuis 7 jours, max 50 commits).
Étape 2 — Sélectionner les repositories et branches
Ciblez les repos et, si souhaité, indiquez des branches particulières ou activez le traitement sur toutes les branches (attention à l’explosion du volume).
Étape 3 — Simuler les pushs et déclencher les hooks
Le système simule des événements de push pour chaque commit trouvé et déclenche les hooks/agents configurés, en respectant le rate limiter et les retries.
Étape 4 — Suivre la progression
Suivez les progrès via la console de tâches ; la progression est poussée en temps réel vers le client. Si la connexion est interrompue, vous pouvez la rétablir et poursuivre le suivi.
Étape 5 — Vérifier la cohérence des outputs
À la fin du traitement, vérifiez les livrables et logs : documents générés, vecteurs insérés, notifications envoyées.
Avant : récupérer et traiter manuellement chaque commit provoquait des rafales d’appels au provider, risque de blocage pour quota.
Après : traitement via file d’attente + retries permet d’échelonner les requêtes, réduire erreurs et garantir complétion progressive.
Annulation : comportements et limites à connaître
Annuler un job en file d’attente tente d’empêcher son exécution ultérieure, mais toute étape déjà envoyée à un fournisseur externe (p. ex. un appel vers un service tiers) peut ne pas être interrompue. Préparez des compensations ou vérifications post-annulation pour détecter et corriger les effets partiels.
Workflow : Annuler des jobs en cours (procédure recommandée)
Étape 1 — Identifier les jobs à annuler
Consultez la liste des jobs en cours ou en file pour choisir ceux à annuler (par projet, date, type).
Étape 2 — Demander annulation
Soumettez la requête d’annulation. Le système tentera d’arrêter les jobs : ceux qui sont encore dans la file seront retirés ; ceux déjà traités côté fournisseur peuvent aboutir partiellement.
Étape 3 — Déconnecter les notifications si nécessaire
Si vous suivez la progression via socket, nettoyez/fermez la connexion client pour éviter des updates obsolètes.
Étape 4 — Vérifier l'état final
Après annulation, vérifiez les statuts pour chaque job. Pour les actions partielles, lancez des tâches de correction ou nettoyage.
Étape 5 — Nettoyage local
Supprimez les états temporaires locaux (stockage local) et réinitialisez les compteurs de progression si besoin.
Préparez des tâches compensatoires
Quand une annulation risque de laisser des opérations partielles (ex. documents importés partiellement), créez des tâches de nettoyage ou de réconciliation récurrentes pour garantir la cohérence.
Workflow : Surveiller la progression et gérer la reconnexion socket
Étape 1 — Initialiser l'écoute des événements
Connectez-vous au service de progression en temps réel pour recevoir les mises à jour des jobs (émissions de pourcentage, étapes, messages).
Étape 2 — Stocker l'état localement
Conservez temporairement l’état des jobs dans le stockage local du navigateur pour permettre une restauration de l’affichage après actualisation.
Étape 3 — Reconnexion automatique
Si la connexion est coupée, tentez une reconnexion automatique ; une fois rétablie, demandez au serveur l’état actuel des jobs pour synchroniser l’affichage.
Étape 4 — Demander état si doute
Si vous constatez des divergences (ex. jobs restés à 0%), déclenchez une requête de vérification de statut pour forcer la remise à jour.
Étape 5 — Nettoyage final
Quand tous les jobs atteignent 100 %, supprimez l’état stocké localement et archivez les logs pour audit.
Concurrence élevée (ex. 10+) :
- Avantage : débit maximal.
- Risque : dépassement des quotas, erreurs 429, augmentation des retries.
Concurrence basse (ex. 1–3) + délai intermédiaire :
- Avantage : stabilité, moins d’erreurs.
- Risque : traitement plus long.
La complétion dépend de la charge et des limits
Les travaux sont traités par des workers asynchrones ; la durée de complétion dépend de la charge globale et des limites configurées. En période de forte charge, attendez-vous à des délais plus longs.
Frequently Asked Questions
Exemples d'usage courants
- Ré-indexation d’un dépôt après un backfill : soumettre les commits récents via le flux de traitement, en veillant à limiter la cadence d’insertion de vecteurs.
- Tâches quotidiennes de résumé : planifier un hook “tous les 1 jour” et s’assurer que l’exécution est fractionnée si elle doit traiter beaucoup de données.
- Uploads massifs : mettre en file d’attente les téléchargements et limiter la concurrence pour éviter les erreurs réseau.
Documentez vos paramètres par projet
Conservez une fiche par projet (concurrence, délai, stratégie de retry, fréquence des hooks). Cela facilite le tuning et les audits.
Pièges fréquents
- Ne pas tenir compte des appels externes déclenchés par vos jobs (ex. webhooks) peut entraîner des effets en cascade.
- Modifier les limites en production sans monitoring peut provoquer des interruptions de service tiers.
Besoin d'aide pour configurer vos limites et scheduler ?
Si vous hésitez sur les paramètres à appliquer ou voulez un tuning adapté à votre charge, contactez l’équipe d’infra pour une recommandation personnalisée.