Périmètre sûr : ce guide couvre vos propres applications, en QA comme en production, et tout système pour lequel vous disposez d'une autorisation écrite.
Une intégration CAPTCHA ne tombe jamais en panne bruyamment : elle ralentit, puis échoue une exécution sur dix, et personne ne le voit avant le premier ticket de support. Superviser, c'est transformer ce silence en signal. Trois mesures suffisent : temps de résolution, taux de réussite, écart entre « token obtenu » et « requête acceptée ». BetterStack en est la destination — moniteurs, heartbeats, logs.
Les deux courbes à ne jamais confondre
Un token renvoyé n'est pas un workflow réussi. Tracez séparément la réussite des résolutions et l'acceptation côté métier : l'écart est votre meilleur détecteur de régression. Il grimpe dès qu'un sitekey change ou qu'un token part dans une session autre que celle du défi.
Étape 1 : isolez l'environnement et sécurisez la clé
Vérifiez que la QA est séparée de la production et que la clé API vit dans un coffre ou un secret de CI. Étiquetez chaque métrique par environnement (dev, staging, prod) : sinon un pic en préproduction réveillera l'astreinte à trois heures du matin.
Étape 2 : instrumentez l'appel de résolution
Encapsulez l'appel à CaptchaAI dans une fonction unique qui reçoit le sitekey et l'URL de votre page, retourne le token et émet quatre valeurs : durée totale, code retour HTTP, identifiant de tâche et profondeur de la file d'attente. Une seule porte d'entrée, une seule source de métriques.
Étape 3 : vérifiez le token côté backend
Le token doit être validé par votre backend avant toute action métier. Cette étape produit le taux d'acceptation : émettez-le sous le même identifiant de corrélation que l'appel de résolution, sinon les deux courbes resteront incomparables.
Exemple : créer une tâche Turnstile et la chronométrer
Encadrez cet appel d'un chronomètre et exportez la durée avec le code retour.
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Étape 4 : branchez les signaux sur BetterStack
Heartbeat pour les jobs planifiés
Un cron nocturne qui ne démarre pas ne produit aucune erreur : c'est la panne la plus difficile à voir. Créez un heartbeat, appelez son URL à chaque exécution réussie, puis pointez un moniteur HTTP vers un endpoint de santé qui exécute un vrai cycle.
Seuils d'alerte
Ne recopiez pas des seuils trouvés en ligne : mesurez une semaine normale, puis alertez sur la dérive. Deux règles suffisent — latence médiane doublée pendant dix minutes, ou écart réussite/acceptation supérieur à cinq points.
Journalisation, RGPD et corrélation
Séparez les journaux par environnement et gardez un identifiant de corrélation compatible avec votre traçage distribué (OpenTelemetry). Côté conformité, appliquez la minimisation : ni adresse IP ni contenu de formulaire dans les journaux. Des workers chez OVHcloud ou Scaleway en région parisienne gardent une latence réseau stable, donc lisible.
Dimensionner les threads pour éviter les fausses alertes
La facturation CaptchaAI repose sur les threads simultanés, résolutions illimitées par thread. Quand ils sont tous occupés, les tâches attendent : cette attente ressemble à une hausse de latence, pas à une erreur. Comparez la profondeur de file à votre plafond avant d'accuser le solveur. Quelques centaines de vérifications QA par jour tiennent sur BASIC ($15/mois, 5 threads) ; un pipeline continu justifie ADVANCE ($90/mois, 50 threads), facturés en dollars US.
Liste de contrôle
- Clé API dans un coffre ou un secret de CI, jamais dans le dépôt.
- Étiquette d'environnement et identifiant de corrélation par métrique.
- Latence, taux de réussite et taux d'acceptation tracés séparément.
- Un heartbeat par job planifié, avec période de grâce réaliste.
- Retries bornés, rétention des logs conforme au RGPD.
FAQ
Quel est le premier tableau de bord à construire ?
Un graphe à deux courbes : réussite des résolutions et acceptation backend sur la même échelle de temps, plus la latence médiane et le 95e centile.
Faut-il alerter sur chaque erreur de l'API ?
Non : les erreurs transitoires sont absorbées par vos retries. Alertez sur des taux et des durées, pas sur des événements unitaires. Réservez l'alerte immédiate à trois cas : clé invalide, solde épuisé, absence de heartbeat.
Quelles données conserver dans les logs sans risque RGPD ?
Identifiant de tâche, horodatage, durée, code retour et environnement suffisent. N'y stockez ni tokens, ni données de formulaire, ni adresses IP.
Une hausse de latence signifie-t-elle que le service se dégrade ?
Pas nécessairement. Vérifiez d'abord l'occupation de vos threads : une saturation locale produit la même courbe. Comparez aussi les types de CAPTCHA appelés : leurs temps de résolution diffèrent.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en CI
- Résoudre reCAPTCHA v2 via API
Mesurez avant de deviner : une intégration instrumentée se répare en minutes. – Obtenez votre clé CaptchaAI.
