Tracer les appels CaptchaAI dans Grafana Tempo

Périmètre sûr : ce guide vise vos applications et les systèmes que vous êtes autorisé à automatiser. Ni sites tiers, ni anti-détection.

Une résolution CAPTCHA de 40 secondes ne se voit pas dans vos logs : elle apparaît comme un trou dans la trace, entre la requête entrante et l'écriture en base. Le traçage CAPTCHA dans Grafana Tempo remplit ce trou — un span par appel CaptchaAI, avec la durée d'envoi, la durée de polling et le verdict du backend. La question « solveur ou réseau ? » se tranche alors en trente secondes.

Ce qu'un span d'appel CAPTCHA doit contenir

Modélisez chaque résolution comme un span parent et deux enfants : envoi, puis interrogation du résultat. Cette découpe distingue une file d'attente saturée d'une réponse lente. Quatre attributs sur le parent suffisent :

N'y placez jamais la clé API, l'IP de l'utilisateur ni le token : les traces s'exportent, et le RGPD s'applique à leur contenu.

Préparer l'environnement

Trois vérifications avant d'écrire une ligne de code : le collecteur OpenTelemetry expose un endpoint OTLP joignable depuis vos workers, la clé CaptchaAI vit dans un secret CI, la QA est isolée de la production. Un collecteur injoignable tronque les traces sans rien signaler.

Étape 1 : encapsuler l'appel dans une fonction traçable

Isolez l'appel CaptchaAI dans une fonction unique : elle reçoit le sitekey et l'URL de page, ouvre le span, retourne le token, puis le referme avec sa durée et son code retour.

Étape 2 : envoyer la tâche et capturer l'identifiant

L'envoi renvoie le taskId. Attachez-le au span aussitôt : sans lui, une trace lente reste impossible à diagnostiquer.

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 3 : corréler la trace et la vérification backend

Votre backend doit vérifier le token avant toute opération métier. Propagez le contexte de trace jusqu'à cet appel : une seule trace porte alors la chaîne « défi affiché → token obtenu → token accepté », et révèle le défaut le plus fréquent — un token correct appliqué dans une autre session, donc refusé.

Étape 4 : exploiter les traces dans Grafana

Une recherche TraceQL filtrée à plus de 30 s sort la queue de distribution.

Ajoutez deux panneaux : médiane et P95 par captcha.type, puis l'écart entre tokens obtenus et tokens acceptés. Un écart qui se creuse pointe vers la session ou le sitekey, pas vers le solveur — ces chiffres varient selon l'environnement et le volume.

Exemple : une équipe SaaS entre Paris et Montréal

Une équipe QA dont les workers tournent sur OVHcloud et l'API sur AWS eu-west-3 (Paris) voit des pics de latence côté québécois. La trace tranche : envoi court et polling long, la résolution attend en file d'attente ; deux spans longs, c'est le réseau. Le premier cas se règle par les threads — CaptchaAI facture au thread simultané, résolutions illimitées : BASIC ($15/mois, 5 threads), VIP-3 ($7,500/mois, 5 000 threads).

Liste de contrôle avant mise en production

FAQ

Quels attributs de span poser sur un appel CaptchaAI ?

Quatre suffisent : type, identifiant de tâche, tentative et verdict final. Le token, la clé API et l'adresse IP n'ont rien à faire dans une trace.

Comment distinguer une lenteur du solveur d'une lenteur réseau ?

Comparez les deux spans enfants. Envoi rapide, polling long : la résolution attend. Deux spans lents : regardez le réseau ou le TLS.

Combien de temps conserver ces traces ?

Alignez-vous sur vos autres traces, souvent 7 à 30 jours. Avec les attributs ci-dessus, aucune donnée personnelle n'y figure : reste un coût de stockage.

CaptchaAI prend-il en charge hCaptcha pour ces mesures ?

Non — hCaptcha et FunCaptcha ne sont pas pris en charge, et GeeTest v4 est à venir. Instrumentez reCAPTCHA v2 et v3, Cloudflare Turnstile, GeeTest v3 et l'image/OCR ; CaptchaFox, Friendly Captcha et Lemin (bêta) suivent le même modèle.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnement autorisé
• Tester l'endpoint API
• CAPTCHA en intégration continue
• Résoudre reCAPTCHA v2 via l'API

Instrumentez d'abord, optimisez ensuite. – Obtenez votre clé CaptchaAI.