Centraliser les logs CaptchaAI dans Grafana Loki

Périmètre sûr : ce guide vise vos propres applications et les environnements que vous exploitez ou pour lesquels vous détenez une autorisation écrite.

« Pourquoi cette tâche a-t-elle mis 90 secondes hier soir ? » Sans logs centralisés, l'incident se referme sur une hypothèse. Centraliser les logs CaptchaAI dans Grafana Loki consiste à écrire chaque appel en JSON, à l'étiqueter avec deux ou trois labels stables, puis à tout interroger en LogQL depuis le tableau de bord de votre équipe : temps de résolution, codes d'erreur et taux de réussite.

Écrire du JSON, pas des phrases

Loki n'indexe pas le contenu des lignes : il les stocke telles quelles et les filtre à la lecture. Une ligne JSON à plat s'analyse donc bien mieux qu'un message rédigé, puisque | json | duration_ms > 20000 fonctionne immédiatement. Ajoutez-y votre trace_id OpenTelemetry, jamais le token ni la clé API : un log est répliqué et lu par toute l'équipe.

Instrumenter l'appel CaptchaAI

Encapsulez l'appel dans une fonction unique : c'est là que se mesurent la durée et le code retour, et que s'émet la ligne de log. L'exemple ci-dessous crée une tâche Turnstile ; entourez-le d'un chronomètre et d'une sérialisation JSON vers stdout.

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

Les cinq champs à tracer à chaque appel

Choisir des labels Loki à faible cardinalité

C'est l'erreur classique. Loki crée un flux distinct par combinaison de labels : déclarez task_id en label et vous fabriquez des millions de flux, et l'index s'effondre. Trois labels suffisent : app, env (dev, staging, prod) et captcha_type. Le reste — identifiants, URL, durées — vit dans la ligne JSON, que LogQL filtre à la requête.

Acheminer les logs jusqu'à Loki

En conteneurs, le driver de logs Docker ou un agent Grafana Alloy en DaemonSet lit stdout et pose les labels. Une équipe hébergée chez Scaleway ou OVHcloud gagne à placer Loki dans la région de ses workers, à Paris ou à Gravelines : l'ingestion reste rapide et les journaux ne quittent pas l'Union européenne.

Les requêtes LogQL à garder sous la main

Trois requêtes couvrent l'essentiel. La latence médiane par famille : quantile_over_time(0.5, {app="captcha-worker"} | json | unwrap duration_ms [5m]) by (captcha_type). Le volume d'échecs par code : sum by (error_code) (count_over_time({app="captcha-worker"} | json | status="error" [15m])). Enfin le taux de réussite, en rapportant les lignes status="ok" au total de la fenêtre. Épinglés côte à côte, ces panneaux font apparaître les dérives tôt.

Alerter sans noyer l'équipe, et purger à temps

Deux alertes valent mieux que dix : la latence P95 au-delà de votre timeout applicatif, et l'apparition d'ERROR_ZERO_BALANCE, qui annonce l'arrêt du pipeline. Surveillez aussi la saturation des threads : un plan ADVANCE ($90/mois, 50 threads) sollicité par 50 appels simultanés met les tâches suivantes en file d'attente, et la latence grimpe. Côté rétention, appliquez la minimisation prévue par le RGPD : trente jours suffisent presque toujours, et aucune donnée personnelle n'a sa place ici.

Liste de contrôle avant la mise en production

FAQ

Quels labels utiliser pour les logs CaptchaAI dans Loki ?

Trois suffisent : app, env et captcha_type — cardinalité bornée, filtres utiles couverts. Les identifiants de tâche restent dans le corps JSON.

Faut-il journaliser le token renvoyé par l'API ?

Non. Le token est une donnée d'authentification éphémère : inutile au diagnostic, il finit dupliqué dans vos sauvegardes. Tracez le task_id, la durée et le statut.

Comment calculer un taux de réussite en LogQL ?

Comptez les lignes status="ok" sur une fenêtre, divisez par le total de la même fenêtre avec count_over_time et agrégez by (captcha_type). Affichez-le sur un panneau Stat.

Combien de temps conserver ces journaux ?

Trente jours couvrent presque tous les besoins ; au-delà, agrégez en métriques plutôt que de garder les lignes brutes. Vérifiez vos obligations RGPD avant de fixer la durée.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Brancher la résolution CAPTCHA sur votre CI
• Résoudre reCAPTCHA v2 via l'API

Passez de la ligne de log au tableau de bord : ouvrez votre compte CaptchaAI et instrumentez votre premier appel.