Tracer les appels CaptchaAI dans Baselime

Périmètre sûr : ce guide couvre vos propres applications — QA, préproduction, production — ou des systèmes pour lesquels vous détenez une autorisation écrite.

Le diagnostic d'un échec CaptchaAI se joue avant l'incident, pas pendant. Sans instrumentation, il ne reste qu'un timeout isolé dans un log. La règle tient en une phrase : chaque résolution produit un span nommé, avec sa durée, son identifiant de tâche et son résultat, exporté vers Baselime comme n'importe quelle requête HTTP. Reste à savoir quoi y mettre.

Les quatre attributs qui rendent un appel CAPTCHA lisible

Un span sans attributs ne sert à rien : vous saurez qu'un appel a duré 22 s, jamais pourquoi. Attachez ces quatre valeurs.

Le dernier est le plus souvent oublié : une tâche résolue et un formulaire accepté sont deux mesures distinctes, et l'écart révèle les vrais défauts d'intégration.

Encapsuler l'appel dans une fonction unique

Un seul point d'entrée vers CaptchaAI dans toute la base de code : une fonction qui reçoit le sitekey et l'URL de la page, ouvre le span, renvoie le token et referme ce span quoi qu'il arrive. Sinon l'instrumentation se disperse entre trois services et deux n'exporteront rien.

Exemple Node.js : créer la tâche et récupérer son identifiant

C'est autour de l'appel ci-dessous que vous ouvrez le span et enregistrez captcha.task_id.

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;
}

Vérifier le token côté backend

Le token repasse par votre backend avant toute opération métier : cette vérification écarte les tokens périmés. Tracez son résultat dans le même span parent que la résolution, sinon vous perdez le lien entre « résolu » et « accepté ».

Préparer l'environnement avant d'instrumenter

Isolez la QA de la production, stockez la clé API dans un coffre ou un secret CI — jamais dans le dépôt — et vérifiez que vos endpoints internes acceptent le trafic de test. Une équipe dont les workers tournent sur OVHcloud, Scaleway ou la région eu-west-3 gagne à séparer ses clés par environnement, ne serait-ce que pour lire ses graphes de latence.

Côté RGPD, journalisez l'identifiant de tâche et l'URL de la page, jamais le contenu des formulaires.

Corréler les traces d'un environnement à l'autre

Propagez un identifiant de corrélation unique du déclenchement du job jusqu'à la soumission du formulaire. Avec OpenTelemetry, le trace ID suffit : Baselime reconstitue la chronologie, de la création de la tâche à la réponse du backend. En incident, un seul identifiant suffit au diagnostic.

Les alertes qui méritent un réveil

1. Médiane de résolution en hausse durable sur une heure glissante : file d'attente saturée ou threads insuffisants.
2. Écart « résolu » / « accepté » qui se creuse : le token est valide, mais la page le refuse.
3. Erreurs transitoires au-delà de votre budget de retry (trois tentatives, backoff plafonné à 30 s).
4. Solde du compte sous votre seuil, avant le rejet des tâches.

Checklist avant la mise en production

• Le périmètre reste limité à vos applications ou à des sources autorisées.
• La clé API vit dans un coffre ou un secret CI.
• Chaque appel produit un span avec durée, type, identifiant et résultat.
• Les retries sont bornés et journalisés.

Questions fréquentes

Quelles métriques suivre en priorité dans Baselime ?

Trois suffisent : la médiane et le P95 du temps de résolution, le taux d'échec par type de défi, et l'écart entre tâches résolues et soumissions acceptées.

Combien de threads prévoir pour un pipeline de QA nocturne ?

Comptez les résolutions simultanées à la minute de pointe, pas le volume total : la facturation CaptchaAI repose sur les threads, avec un nombre de résolutions illimité par thread. Dix scénarios en parallèle tiennent sur STANDARD ($30/mois, 15 threads) ; un parc de workers plus large passe à ADVANCE ($90/mois, 50 threads).

Comment relier une trace Baselime à une tâche CaptchaAI ?

Enregistrez l'identifiant de tâche comme attribut du span dès sa création : une recherche sur cet attribut ramène la trace entière, retries compris.

Que faire d'un appel qui expire régulièrement ?

Vérifiez la configuration réseau (DNS, certificats, proxy sortant) puis le nombre de threads de votre plan. Si le timeout ne touche qu'un type de défi, comparez les paramètres envoyés avec la page : un sitekey obsolète produit ce symptôme.

Guides connexes

• Le démarrage rapide CaptchaAI
• La QA CAPTCHA en environnement autorisé
• Tester l'endpoint API sur vos formulaires
• Le CAPTCHA en intégration continue
• Résoudre reCAPTCHA v2 via l'API

Créez votre clé CaptchaAI et tracez votre premier appel dans Baselime dès ce soir.