Cómo supervisar las tasas de éxito del solucionador de Turnstile en Python

Resumen

• Supervise los resultados del solucionador de Turnstile, la validación del token y la finalización de la aplicación como resultados separados.
• Un taskId de CapSolver confirma la creación de la tarea; una respuesta ready que contiene el token esperado confirma un resultado del solucionador.
• Las analíticas del widget de Cloudflare y tus registros del solucionador cuentan eventos distintos, por lo que sus porcentajes no deben compararse sin igualar las definiciones.
• Mide por separado el tiempo hasta el resultado del solucionador y el tiempo hasta el resultado final de la aplicación, incluyendo fallos e intentos no resueltos.
• Usa evidencia de Siteverify solo cuando operes la aplicación protegida o tengas acceso autorizado a sus registros de validación.
• Usa un registro por intento en el resumen de Python, y cuenta un flujo de trabajo reintentado una sola vez para la métrica de finalización de la aplicación.

Un trabajo programado en el navegador recibe un token de Turnstile, pero la página nunca alcanza su confirmación esperada. El panel del solucionador parece saludable mientras que el equipo de operaciones sigue viendo trabajos fallidos. ¿A qué número deberían hacer caso?

Ambas observaciones pueden ser correctas. El solucionador devolvió un resultado; la aplicación no ha confirmado la finalización. Las métricas útiles del solucionador de Cloudflare Turnstile muestran dónde divergen esos resultados. CapSolver proporciona la respuesta de la tarea de resolución, mientras que tu flujo de trabajo en el navegador y, cuando esté disponible, el backend de la aplicación protegida proporcionan el resto de la evidencia. Esta guía explica qué registrar para una integración existente y autorizada y cómo resumir con Python una exportación de registros redactada. Se centra en la supervisión práctica para equipos de QA y servicios de automatización empresarial, sin asumir acceso a las analíticas privadas de un sitio web de terceros.

Define qué puede observar realmente tu panel de Turnstile

El alcance de tu supervisión depende de si controlas el sitio web protegido, el cliente de automatización o ambos.

El propietario de una aplicación puede inspeccionar la actividad del widget, la validación del lado del servidor y la operación final de la aplicación. Un servicio de automatización que trabaja en un recorrido de cliente aprobado puede ver solo sus respuestas del solucionador y los resultados del navegador. Acuerda con el cliente qué evidencia de backend está disponible antes de etiquetar un resultado como “validado”.

Las analíticas de resultados de desafío de Cloudflare describen desafíos emitidos y resueltos, incluyendo resultados interactivos y no interactivos. Esas son observaciones del widget. No son un informe directo de cuántas tareas aceptó o completó tu solucionador CAPTCHA externo.

Mantén separados en el informe los widgets de Turnstile de los desafíos de página completa de Cloudflare. Si el equipo no está seguro de qué punto de control encontró, usa la guía para identificar desafíos de Turnstile y Cloudflare antes de agrupar los intentos. Combinar distintos tipos de desafío hace que un cambio en la carga de trabajo parezca un cambio en la calidad del solucionador.

Registra la solicitud al solucionador y su resultado final

La métrica de resultado del solucionador debe contar las tareas que devuelven la solución esperada, usando un conjunto claramente definido de intentos enviados.

La guía oficial de la API de Turnstile de CapSolver documenta AntiTurnstileTaskProxyLess, con websiteURL y websiteKey como entradas obligatorias. Los metadatos opcionales incluyen los valores action y cdata del widget. Registra un identificador seguro para la configuración utilizada, de modo que un cambio en la entrada pueda compararse con fallos posteriores.

CapSolver usa createTask para enviar la tarea y getTaskResult para recuperar su resultado. El resultado documentado de Turnstile incluye status: ready y solution.token. Un taskId por sí solo no es una solución completada. La referencia de recuperación de resultados explica el manejo de la respuesta que tu integración existente ya debería realizar.

Para la supervisión, conserva un ID de flujo de trabajo y un ID de tarea del solucionador por separado. Una sola operación aprobada del navegador podría crear más de un intento de resolución. Cuenta esos intentos individualmente para las métricas del solucionador, pero cuenta la operación original una sola vez al informar la finalización del flujo de trabajo.

Mantén visibles los fallos y las tareas inconclusas

Elige una fecha límite de observación para cada cohorte de intentos e informa tareas exitosas, fallidas y no resueltas juntas. Una cohorte significa el mismo grupo seleccionado de solicitudes, como las tareas enviadas durante una hora concreta para un flujo de trabajo aprobado.

Para una tasa de resultados conservadora, divide los resultados exitosos del solucionador entre todos los intentos enviados en esa cohorte. Muestra también el recuento de tareas no resueltas; una tasa de resultados medida mientras muchas tareas aún se están ejecutando es provisional. Si en cambio calculas una tasa de tareas completadas, etiqueta explícitamente su denominador más estrecho.

Agrupa errores de creación y de resultado usando las respuestas de error documentadas de CapSolver. Una configuración rechazada y una resolución fallida requieren investigaciones distintas. Ambas pueden afectar al servicio que experimenta tu cliente, pero deben conservar causas diferenciadas.

Separa la validación del token de la finalización en el navegador

La validación de tokens mide si el backend de la aplicación protegida acepta el token de Turnstile mediante Siteverify.

Las métricas de validación de tokens de Cloudflare cuentan las solicitudes a Siteverify y las respuestas con success: true o success: false. Cuando esos registros están disponibles, informa las respuestas válidas divididas por todas las respuestas de validación en la cohorte seleccionada. Mantén los fallos de red sin respuesta en un recuento separado y visible.

El glosario de tokens explica el rol general de un token. En este flujo de trabajo, recibir el token es un evento intermedio. La aplicación todavía tiene que validarlo y completar su propia operación.

Cuando tu servicio no controla el sitio web

Usa un resultado observable de la aplicación, como la página de confirmación esperada o el registro permitido solicitado. Etiqueta esto como “flujo de trabajo completado”, junto con la afirmación que estableció dicha finalización.

No deduzcas una respuesta de Siteverify a partir de un widget en verde, un estado HTTP satisfactorio o la desaparición de un desafío. Si el cliente no ha proporcionado evidencia de validación, informa la validación de tokens como no disponible. Una observación faltante claramente identificada es más útil que una tasa de éxito estimada presentada como si fuera medida.

Para los informes al cliente, conserva el motivo original del fallo cuando el resultado final siga siendo desconocido. “El solucionador devolvió un token; la confirmación no se observó antes de la fecha límite” indica al siguiente ingeniero por dónde empezar.

Canjea tu código de bonificación de CapSolver

Aumenta tu presupuesto de automatización al instante.
Usa el código de bonificación CAP26 al recargar tu cuenta de CapSolver para obtener un 5% de bonificación extra en cada recarga, sin límites.
Canjéalo ahora en tu Panel de CapSolver

Mide la latencia en el paso donde se produce la demora

La supervisión de latencia debe distinguir el tiempo de espera del solucionador, el retraso en la entrega del token y el tiempo total del flujo de trabajo.

Inicia el temporizador del solucionador cuando el cliente envía su solicitud de tarea y deténlo cuando el cliente recibe el resultado esperado o un fallo final. Esto mide el tiempo transcurrido observado por el cliente, incluyendo la red y el sondeo. No aísla el tiempo de procesamiento interno del proveedor.

Registra por separado el intervalo entre la recepción del token y el envío de la solicitud de la aplicación. Un trabajo en el navegador que espera en una cola después de resolver puede crear un problema de token incluso cuando el solucionador respondió con rapidez.

La referencia de validación del lado del servidor de Cloudflare indica que los tokens de Turnstile caducan después de 300 segundos y son de un solo uso. La misma referencia explica los errores de validación y la comprobación de los campos relevantes de la respuesta, incluyendo el nombre de host y la acción esperados. Tu marca de tiempo de recepción es útil para diagnosticar retrasos en la entrega; no es prueba de la vida útil restante exacta del token.

Muestra una mediana y un percentil de cola lenta, como p95, para intentos completados comparables. Añade el tamaño de la muestra y el recuento de tiempos de espera junto a ellos. Un gráfico de latencia solo de éxitos puede parecer más rápido cuando las solicitudes más lentas han superado el tiempo de espera y han desaparecido del cálculo.

Mantén distinguibles las pruebas locales, los workers en la nube, las diferentes familias de páginas y las versiones cambiadas de la integración. Compara el mismo flujo de trabajo antes y después de un despliegue antes de culpar a un cambio del proveedor global.

Usa un panel pequeño con denominadores claros

Un primer panel útil conecta cada métrica con un evento que puedas verificar.

Estas son definiciones a nivel de aplicación propuestas, no afirmaciones de que todos los campos sean suministrados por una respuesta de la API de CapSolver. Calcula solo lo que tus registros y facturación admitan. Cuando el denominador de finalización sea cero, muestra el costo por operación completada como no disponible en lugar de forzar un número engañoso.

Calcula tasas de éxito de Turnstile con Python

Python puede resumir una exportación redactada de tu integración de solucionador existente sin enviar otra solicitud de resolución.

Este ejemplo usa solo la biblioteca estándar de Python 3; no se requiere instalar paquetes ni credenciales de API. Mide los registros que proporciones. No recopila tareas en vivo, no valida tokens ni mide por sí mismo el rendimiento de un proveedor.

Prepara una fila por intento de resolución

Exporta una instantánea en una fecha límite de observación definida. Usa un attempt_id interno incluso cuando la creación de la tarea falle antes de que la API devuelva un ID de tarea. Incluye todos los intentos de tu cohorte de flujo de trabajo seleccionada, incluyendo fallos de creación y tareas aún pendientes. No exportes cada respuesta de sondeo como un intento separado.

Los campos CSV siguientes son un esquema de informes de aplicación, no parámetros de la API de CapSolver:

• solver_result: usa ready solo después de que tu integración reciba un resultado ready exitoso con el token esperado; usa failed para un error final y pending para trabajo no resuelto en la instantánea.
• validation: usa passed o failed solo para una respuesta de validación de backend observada. Usa unknown cuando la evidencia no esté disponible, la validación no se haya ejecutado o no haya llegado ninguna respuesta. Conserva los detalles de errores de transporte en tus registros de diagnóstico separados.
• workflow_completed: usa yes solo cuando se haya confirmado el resultado esperado de la aplicación. Usa el mismo workflow_id a través de los reintentos.

Guarda este conjunto de datos ilustrativo como attempts.csv. Estos cinco registros son ejemplos inventados, no observaciones de producción ni resultados de referencia:

attempt_id,workflow_id,solver_result,validation,workflow_completed
a1,w1,ready,passed,yes
a2,w2,failed,unknown,no
a3,w2,ready,passed,yes
a4,w3,ready,failed,no
a5,w4,pending,unknown,no

Ejecuta el resumen

Guarda el siguiente script como summarize_turnstile.py. La comprobación de IDs duplicados evita que una exportación que contenga filas repetidas de sondeo infle silenciosamente los recuentos.

import csv
import json
import sys
from collections import Counter


def summarize(path):
    with open(path, newline='', encoding='utf-8') as handle:
        rows = list(csv.DictReader(handle))
    seen = set()
    completed = set()
    workflows = set()
    solver = Counter()
    validation = Counter()
    for row in rows:
        attempt = row['attempt_id'].strip()
        workflow = row['workflow_id'].strip()
        if not attempt or attempt in seen or not workflow:
            raise ValueError('Use unique, nonempty attempt IDs and nonempty workflow IDs')
        if row['solver_result'] not in {'ready', 'failed', 'pending'}:
            raise ValueError('Invalid solver_result')
        if row['validation'] not in {'passed', 'failed', 'unknown'}:
            raise ValueError('Invalid validation')
        if row['workflow_completed'] not in {'yes', 'no'}:
            raise ValueError('Invalid workflow_completed')
        seen.add(attempt)
        workflows.add(workflow)
        solver[row['solver_result']] += 1
        validation[row['validation']] += 1
        if row['workflow_completed'] == 'yes':
            completed.add(workflow)

    def percent(numerator, denominator):
        return round(100 * numerator / denominator, 2) if denominator else None

    observed_validation = validation['passed'] + validation['failed']
    return {
        'attempts': len(rows),
        'solver_ready': solver['ready'],
        'solver_failed': solver['failed'],
        'solver_pending': solver['pending'],
        'solver_result_rate_pct': percent(solver['ready'], len(rows)),
        'validation_observed': observed_validation,
        'validation_unknown': validation['unknown'],
        'validation_pass_rate_pct': percent(validation['passed'], observed_validation),
        'workflows': len(workflows),
        'workflows_completed': len(completed),
        'workflow_completion_rate_pct': percent(len(completed), len(workflows)),
    }


if __name__ == '__main__':
    print(json.dumps(summarize(sys.argv[1]), indent=2))

Ejecuta el script desde el directorio que contiene ambos archivos:

python3 summarize_turnstile.py attempts.csv

La muestra produce:

{
  "attempts": 5,
  "solver_ready": 3,
  "solver_failed": 1,
  "solver_pending": 1,
  "solver_result_rate_pct": 60.0,
  "validation_observed": 3,
  "validation_unknown": 2,
  "validation_pass_rate_pct": 66.67,
  "workflows": 4,
  "workflows_completed": 2,
  "workflow_completion_rate_pct": 50.0
}

Tres de los cinco intentos produjeron un resultado del solver, por lo que la tasa de resultados del solver de la muestra es del 60%. Dos de tres validaciones observadas pasaron, dando un 66,67%. Dos de cuatro flujos de trabajo únicos se completaron, dando un 50%. El intento fallido y el reintento exitoso de w2 cuentan como dos intentos pero un solo flujo de trabajo completado.

El recuento pendiente hace que el resultado del 60% sea provisional. Reconstruye la instantánea después de que termine el trabajo pendiente; no agregues otra fila con el mismo ID de intento. Si no hay filas o no hay validaciones observadas, la tasa correspondiente es null en lugar de un cero inventado.

Para un informe por ventana de tiempo, selecciona primero los flujos de trabajo e incluye sus intentos relevantes hasta la fecha límite de observación. Filtrar filas de intentos de forma arbitraria puede dejar fuera un éxito anterior o un reintento posterior y cambiar el denominador de flujos de trabajo. Mantén un recuento aparte de los flujos de trabajo elegibles que nunca llegaron al envío al solver; este pequeño script no puede contar operaciones que faltan en su entrada.

El cálculo local del ejemplo puede reproducirse sin credenciales. Para monitorear tu servicio, sustituye el ejemplo por registros redactados de tu integración real y documenta la cohorte de exportación y la fecha límite de observación. Evita incluir claves de API, tokens en bruto, cookies o contenidos de formularios personales.

Convierte los cambios de métricas en una investigación específica

Investiga la primera etapa cuyo resultado cambió, usando la misma cohorte de flujos de trabajo en todo momento.

Si aumentan los errores de creación de tareas, revisa la configuración y las credenciales antes de incrementar los recuentos de reintentos. Si los resultados del solver se mantienen estables pero aumentan los fallos de validación, revisa las categorías de errores de validación y el momento de la transferencia de tokens. Si la validación se mantiene estable pero disminuye la finalización de la aplicación, revisa la aserción final, la respuesta del formulario o la salida de datos permitida.

Por ejemplo, un proveedor de QA podría notar que una versión del cliente añade una operación en segundo plano entre la recepción del token y el envío del formulario. La comparación útil es el retraso en la transferencia de ese cliente y los resultados de validación antes y después de la versión. Un porcentaje de éxito agregado en todos los clientes puede ocultar el recorrido afectado.

Trata estos escenarios como rutas de investigación, no como prueba de una causa. Revisa un pequeño número de fallos autorizados con marcas de tiempo antes de cambiar la integración. Mantén los reintentos acotados y preserva el intento original para que los reintentos no inflen el recuento de finalizaciones.

Cloudflare proporciona sitekeys y secret keys de prueba para comprobaciones de implementación controladas. Úsalas para probar las ramas de éxito y fallo de tu propia aplicación. Mantén las pruebas con tokens ficticios fuera de los informes reales de rendimiento del solver: verifican el comportamiento de la aplicación, no la calidad de resolución en producción.

Evita almacenar tokens de solución en bruto, claves de API, cookies o contenidos de página innecesarios en los registros de monitoreo. Los identificadores de flujos de trabajo, identificadores de tareas, marcas de tiempo, categorías de resultados y etiquetas de configuración seguras suelen proporcionar un mejor punto de partida.

Empieza por el resultado que necesita tu cliente

Empieza el monitoreo de Turnstile con tres preguntas separadas: ¿el solver devolvió su resultado?, ¿la aplicación validó el token donde esa evidencia está disponible? y ¿la operación aprobada terminó?

Agrega latencia y costo una vez que esos resultados tengan definiciones estables. Una integración existente de CapSolver puede proporcionar los eventos de tareas del solver; tu aplicación proporciona la evidencia de finalización. Mantener visible esa división facilita la resolución de problemas y los informes a clientes sin construir un sistema de monitoreo sobredimensionado.

Preguntas frecuentes

P: ¿Qué métricas del solver de Cloudflare Turnstile debo rastrear primero?

Rastrea la tasa de resultados del solver, la finalización de flujos de trabajo y el tiempo hasta obtener un resultado observado por el cliente. Agrega los resultados de validación de Siteverify cuando operes el backend protegido o tengas acceso autorizado a sus registros. Muestra siempre los fallos y los intentos no resueltos.

P: ¿Una tarea lista de CapSolver significa que el sitio web aceptó el token?

No. Una tarea lista con el token esperado confirma un resultado del solver. La validación en el sitio web y la operación final de la aplicación son eventos posteriores que necesitan su propia evidencia.

P: ¿Puedo medir el éxito de la validación de tokens en un sitio web que no opero?

Solo cuando el propietario proporcione evidencia de validación autorizada. De lo contrario, informa el resultado del navegador que puedas observar y marca la validación en el backend como no disponible.

P: ¿Por qué puede fallar la validación de Turnstile después de una respuesta rápida del solver?

La reutilización del token, el envío con retraso o problemas de implementación aún pueden afectar la validación. Revisa el error real y la temporización de la aplicación; la entrega rápida del token no demuestra que todos los pasos posteriores fueran correctos.

P: ¿Las tasas de éxito del ejemplo son promesas de rendimiento?

No. Los números del ejemplo ilustran diferentes denominadores. Mide tus propios flujos de trabajo autorizados en condiciones comparables y mantén el tráfico con claves de prueba separado de las observaciones de producción.