Tracer les appels CaptchaAI dans Honeycomb

Périmètre sûr : ce guide vise vos propres applications et environnements autorisés, jamais l'automatisation de sites tiers.

Un appel de résolution qui prend 40 secondes ne casse rien : il ralentit toute la chaîne sans laisser de trace exploitable dans vos logs. Tracer les appels CaptchaAI dans Honeycomb consiste à ouvrir un span dédié autour de la soumission et du polling, puis à y attacher les attributs qui expliquent la durée.

Une heatmap et un BubbleUp séparent ensuite un problème de solveur d'un problème de session.

Ce qu'un span apporte dans Honeycomb

Honeycomb ne répond pas à « le CAPTCHA a-t-il été résolu ? » — votre code le sait déjà — mais à « pourquoi la médiane a-t-elle doublé mardi à 14 h ? ». Sans span dédié, le temps passé dans l'API se dilue dans la requête parente et trois causes deviennent indiscernables : file d'attente saturée, type de CAPTCHA plus lent que prévu, token appliqué dans la mauvaise session.

Repère documenté : moins de 0,5 s pour un CAPTCHA image, moins de 60 s pour reCAPTCHA v2.

Les attributs à attacher au span

Instrumentez peu, mais utilement : cinq attributs couvrent l'essentiel.

Ajoutez le trace_id parent, rien de plus : aucune donnée personnelle dans un dataset conservé des mois, vos obligations RGPD valent aussi pour les traces.

Préparer l'environnement

La clé CaptchaAI vit dans un secret CI, la QA reste isolée de la production, et Honeycomb reçoit un dataset par environnement : sinon une campagne de tests écrase vos courbes.

Encapsuler l'appel dans une fonction tracée

La fonction prend le sitekey et l'URL de votre page, ouvre le span, renvoie le token et referme le span avec la durée et le statut.

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

Enveloppez-le dans votre tracer OpenTelemetry : le SDK expédie les spans vers Honeycomb en OTLP.

Vérifier le token côté backend

La vérification du token par votre backend mérite son span enfant : c'est le seul moyen de mesurer l'écart entre résolution réussie et requête acceptée. Appliquez-le dans la session qui a déclenché le défi CAPTCHA : une session dépareillée reste la première cause de rejet.

Exemple : une suite nocturne à Lyon

Une équipe de trois personnes exécute chaque nuit une suite end-to-end sur des workers OVHcloud, avec un backend en eu-west-3 (Paris) et un formulaire protégé par Cloudflare Turnstile. Elle échoue une nuit sur quatre, sans motif visible.

Les spans révèlent une distribution bimodale : la masse sous 10 s, quelques cas au-delà de 90 s. Un BubbleUp isole un captcha.poll_count élevé sur la plage horaire où un job d'export consomme tous les threads du plan. Le correctif ne touche pas au code : passer de BASIC ($15/mois, 5 threads) à ADVANCE ($90/mois, 50 threads) et décaler le job. La facturation au thread garde le coût prévisible.

Trois requêtes Honeycomb utiles

1. Heatmap de duration_ms par captcha.type — la queue que la moyenne masque.
2. COUNT par captcha.status sur 24 h — un code d'erreur qui surgit signale une clé expirée ou un solde épuisé.
3. P95(duration_ms) face au taux d'acceptation backend — si les courbes divergent, cherchez la session, pas le solveur ; placez l'alerte ici.

Liste de contrôle

• Périmètre limité à vos applications ou sources autorisées.
• Un span par appel : durée, code retour, identifiant de tâche.
• Aucune donnée personnelle dans les attributs.
• Retry borné : trois tentatives, backoff exponentiel, plafond explicite.

FAQ

Honeycomb est-il obligatoire, ou un autre backend OpenTelemetry convient-il ?

N'importe lequel : l'instrumentation reste standard côté OpenTelemetry, et les mêmes spans partent vers Grafana Tempo ou Jaeger sans changer une ligne.

Quel volume de traces cela représente-t-il ?

Deux événements par résolution : 5 000 résolutions quotidiennes en génèrent 10 000. Au-delà, échantillonnez les succès, gardez les échecs.

Comment relier une résolution lente à un build CI ?

Propagez le trace_id du pipeline jusqu'à l'appel CAPTCHA et stockez-le dans les artefacts de build : un numéro de build suffit ensuite.

Que tracer lors d'une erreur transitoire ?

Un seul span, marqué en erreur avec le code retour brut, et un attribut retry.attempt incrémenté. Si l'erreur persiste, contrôlez le réseau et votre solde.

Guides connexes

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

Instrumentez d'abord : un span par résolution vous dira où part le temps. – Obtenez votre clé CaptchaAI.