Centraliser les logs CaptchaAI dans Axiom

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.

Quand une résolution CAPTCHA échoue en pleine nuit, il ne reste presque rien à lire : le worker voit un timeout, l'application voit un formulaire refusé, et personne ne sait lequel des deux a lâché. Centraliser les logs CaptchaAI dans Axiom règle ce point en une soirée : un événement JSON par résolution, corrélé à votre trace applicative, et vous tenez la latence réelle, le taux de réussite et le comportement des retries. Voici le schéma d'événement, l'instrumentation et les garde-fous RGPD.

Étape 1 : isolez l'environnement et sortez la clé du code

Quatre décisions à prendre avant d'écrire une ligne :

• la QA tourne sur une infrastructure séparée de la production ;
• la clé CaptchaAI vit dans un coffre ou un secret CI ;
• vos endpoints internes acceptent les requêtes de test ;
• un dataset Axiom par environnement (captcha-dev, captcha-prod), pour régler droits et rétention séparément.

Étape 2 : instrumentez l'appel CaptchaAI dans une fonction unique

Encapsulez la résolution dans une seule fonction : elle reçoit le sitekey et l'URL de votre page, renvoie le token, et émet un événement quoi qu'il arrive — succès comme échec. Mesurez la durée avec une horloge monotone, capturez l'identifiant de tâche, n'avalez jamais une exception sans la journaliser. La fonction Node.js ci-dessous crée la tâche Turnstile ; le chronomètre et l'événement se greffent autour.

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 : validez le token côté backend avant l'action métier

Le token n'a de valeur qu'une fois vérifié par votre backend. Journalisez cette vérification à part : une réussite élevée côté solveur avec une acceptation en baisse pointe vers une session désynchronisée, pas vers l'API.

Étape 4 : le schéma d'événement à envoyer dans Axiom

Un log exploitable tient en cinq champs aux noms stables.

Corrélez les résolutions avec vos traces OpenTelemetry

Propagez le trace_id du span courant dans l'événement CAPTCHA. Un filtre sur ce seul champ ramène toute la chaîne : requête entrante, résolution, vérification backend, réponse. Le diagnostic passe alors de trente minutes de lecture de logs à deux requêtes.

Rétention et RGPD : ce qu'il ne faut pas journaliser

Un log de résolution n'a besoin ni des cookies de session, ni de l'e-mail du compte de test, ni de l'URL complète. Tronquez l'URL au chemin, hachez les identifiants conservés, fixez une rétention par dataset. Pour une équipe française ou belge, c'est la façon la plus simple de documenter la minimisation en audit.

Trois alertes qui suffisent au quotidien

• outcome: error au-dessus de 5 % sur 15 minutes : clé, solde ou paramètre invalide.
• P95 de duration_ms supérieur à votre timeout : vous abandonnez des résolutions qui aboutissaient.
• Écart entre résolutions réussies et vérifications acceptées : le token part dans une autre session.

Cas concret : une équipe QA lyonnaise teste sur des workers Scaleway à Paris, avec un plan BASIC ($15/mois, 5 threads). La médiane reste stable, mais le P95 double vers 9 h : la campagne nocturne déborde et sature les cinq threads. Le correctif est un décalage de planification, pas un changement d'API.

Liste de contrôle avant la mise en production

• Clé CaptchaAI en coffre ou secret CI, jamais en clair.
• Un événement par résolution, erreurs et timeouts compris.
• trace_id propagé jusque dans le log CAPTCHA.
• Retry borné : trois tentatives, backoff exponentiel, échec tracé.
• Rétention validée avec votre référent RGPD.

FAQ

Quelles données faut-il exclure des logs de résolution ?

Tout ce qui identifie une personne : e-mails, cookies, en-têtes d'authentification, URL contenant un identifiant de compte. Gardez le type de CAPTCHA, la durée, le code retour et les identifiants techniques, qui suffisent au diagnostic.

Combien de temps conserver ces journaux ?

Assez pour couvrir un cycle de release et une enquête post-incident : 30 jours en développement, 90 en production. Au-delà, agrégez en métriques quotidiennes.

Comment retrouver un échec précis depuis un ticket support ?

Filtrez le dataset sur le trace_id fourni par l'application, puis lisez la séquence complète. Le champ task_id donne la référence à transmettre au support CaptchaAI si la résolution est en cause.

Guides connexes

• le démarrage rapide CaptchaAI
• la QA CAPTCHA en environnements autorisés
• tester l'endpoint API sur vos formulaires
• intégrer la résolution CAPTCHA à votre CI
• résoudre reCAPTCHA v2 via l'API

Vos résolutions méritent mieux qu'un print() perdu dans un worker. – Obtenez votre clé CaptchaAI.