Observabilité des pipelines CAPTCHA avec OpenTelemetry (2026)

Périmètre sûr : ce guide vise vos propres applications — QA, préproduction, production — ou des systèmes pour lesquels vous détenez une autorisation écrite. Il ne couvre pas l'automatisation de sites tiers.

Un pipeline CAPTCHA mal instrumenté ne tombe pas en panne : il ralentit, et personne ne sait depuis quand. Trois signaux rendent le problème visible : le temps de résolution du token, le code retour de l'API et le statut de la requête qui suit. Voici comment les tracer avec OpenTelemetry.

Réussite du solveur et réussite du workflow : deux taux distincts

Étape 1 : isoler l'environnement et sécuriser la clé

Séparez la QA de la production et stockez la clé CaptchaAI dans un coffre ou un secret CI, jamais dans le dépôt. Ajoutez l'attribut deployment.environment à votre ressource OpenTelemetry : sans lui, vos tableaux de bord mélangeront les environnements au premier incident.

Étape 2 : encapsuler l'appel dans une fonction tracée

Enveloppez l'appel dans une fonction unique qui reçoit le sitekey et l'URL de votre page, ouvre un span dédié et retourne le token. Le span porte la durée, le code retour et l'identifiant de tâche. Changer de type — reCAPTCHA v2, Turnstile, GeeTest v3 — ne touche plus à l'instrumentation.

Étape 3 : valider le token côté backend

• Vérifiez le token côté serveur avant toute opération métier.
• Restez dans la session qui a déclenché le défi CAPTCHA.
• Ouvrez un span enfant dédié : les tokens appliqués dans la mauvaise session s'y repèrent immédiatement.

Exemple : créer une tâche Turnstile en Node.js

L'appel de création de tâche Turnstile, à envelopper dans le span de l'étape 2 :

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

Attributs OpenTelemetry à renseigner

Ces valeurs varient selon l'environnement : mesurez les vôtres avant de fixer un seuil.

Scénario : un pipeline CAPTCHA tracé chez OVHcloud

Une équipe QA lyonnaise teste chaque nuit son propre portail client, protégé par Turnstile, depuis un worker OVHcloud. Un filtre sur captcha.outcome = timeout montre que les échecs se concentrent sur une tranche horaire : c'est le parallélisme qu'il faut ajuster, pas le code. Sur le plan STANDARD ($30/mois, 15 threads), facturé au thread avec des résolutions illimitées, monter les threads la nuit ne change pas la facture.

Corréler logs et traces CAPTCHA par environnement

Propagez le trace_id dans chaque ligne de log autour de l'appel CAPTCHA et séparez les journaux par environnement : un identifiant suffit alors à rejouer un scénario complet. Côté RGPD, tracez des identifiants techniques, jamais les données saisies dans le formulaire.

Contrôles avant mise en production

• Périmètre limité à vos applications ou à des sources autorisées.
• Clé CaptchaAI en coffre ou en secret CI, jamais dans le code source.
• Un span par appel : durée, code retour, identifiant de tâche.
• Retry idempotent plafonné et campagnes rejouables depuis votre CI.
• Acceptation en aval suivie séparément de la réussite du solveur.

FAQ

Quels attributs faut-il ajouter en priorité aux spans CAPTCHA ?

Quatre suffisent : type de CAPTCHA, identifiant de tâche, durée en millisecondes et issue (ok, timeout, error). Ils suffisent à sortir une médiane, un P95 et un taux de réussite par famille.

Comment distinguer un échec de résolution d'un rejet côté applicatif ?

Par deux spans. Si la résolution finit en ok mais que le span de vérification renvoie une erreur, la cause est côté applicatif : session différente, cookies perdus ou token expiré. L'inverse pointe vers les paramètres envoyés au solveur.

Combien de threads prévoir pour un pipeline instrumenté ?

Un thread correspond à une résolution simultanée, pas à un volume mensuel. Une campagne CI séquentielle tient sur BASIC ($15/mois, 5 threads) ; un parc de workers parallèles justifie ADVANCE ($90/mois, 50 threads). Vos spans donnent le pic de résolutions concurrentes.

Le traçage des appels CAPTCHA pose-t-il un problème RGPD ?

Pas si vous vous en tenez aux métadonnées techniques : les attributs recommandés ici ne contiennent aucune donnée personnelle. N'enregistrez ni les valeurs de formulaire, ni les adresses IP, ni le token complet.

Guides connexes

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

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