Como Monitorar as Taxas de Sucesso do Solver Turnstile em Python

Resumo

• Monitore separadamente os resultados do solver Turnstile, a validação do token e a conclusão da aplicação.
• Um task ID da CapSolver confirma a criação da task; uma resposta ready contendo o token esperado confirma um resultado do solver.
• As análises do widget da Cloudflare e os seus logs do solver contam eventos diferentes, então suas porcentagens não devem ser comparadas sem alinhar as definições.
• Meça o tempo até o resultado do solver e o tempo até o resultado final da aplicação separadamente, incluindo falhas e tentativas não resolvidas.
• Use evidências do Siteverify apenas quando você opera a aplicação protegida ou tem acesso autorizado aos logs de validação dela.
• Use um registro por tentativa no resumo em Python e conte um workflow refeito apenas uma vez para a conclusão da aplicação.

Um job de navegador agendado recebe um token Turnstile, mas a página nunca chega à confirmação esperada. O painel do solver parece saudável enquanto a equipe de operações continua vendo jobs falhos. Em qual número eles devem confiar?

Ambas as observações podem estar corretas. O solver retornou um resultado; a aplicação não confirmou a conclusão. Métricas úteis de solver para Cloudflare Turnstile mostram onde esses resultados divergem. A CapSolver fornece a resposta da task de resolução, enquanto o seu fluxo no navegador e, quando disponível, o backend da aplicação protegida fornecem as demais evidências. Este guia explica o que registrar para uma integração existente e autorizada e como resumir uma exportação de logs redigidos com Python. Ele se concentra em monitoramento prático para equipes de QA e serviços de automação corporativos, sem pressupor acesso às análises privadas de um site de terceiros.

Defina o que o seu painel do Turnstile realmente consegue observar

O seu escopo de monitoramento depende de você controlar o site protegido, o cliente de automação ou ambos.

Um dono de aplicação pode inspecionar a atividade do widget, a validação server-side e a operação final da aplicação. Um serviço de automação que trabalha em uma jornada de cliente aprovada pode ver apenas suas respostas do solver e os resultados do navegador. Combine com o cliente quais evidências de backend estarão disponíveis antes de rotular um resultado como “validado”.

As análises de resultado de desafio da Cloudflare descrevem desafios emitidos e resolvidos, incluindo resultados interativos e não interativos. Essas são observações do widget. Elas não são um relatório direto de quantas tasks o seu solver CAPTCHA externo aceitou ou concluiu.

Mantenha os widgets Turnstile separados dos desafios de página inteira da Cloudflare no relatório. Se a equipe não tiver certeza de qual checkpoint foi encontrado, use o guia de identificação de desafios Turnstile e Cloudflare antes de agrupar as tentativas. Combinar tipos diferentes de desafio faz uma mudança na carga de trabalho parecer uma mudança na qualidade do solver.

Registre o pedido ao solver e o resultado final dele

A métrica de resultado do solver deve contar tasks que retornam a solução esperada, usando um conjunto claramente definido de tentativas enviadas.

O guia oficial da API CapSolver Turnstile documenta AntiTurnstileTaskProxyLess, com websiteURL e websiteKey como entradas obrigatórias. Metadados opcionais incluem os valores action e cdata do widget. Registre um identificador seguro para a configuração usada, para que uma alteração na entrada possa ser comparada com falhas posteriores.

A CapSolver usa createTask para enviar a task e getTaskResult para recuperar o resultado. O resultado documentado do Turnstile inclui status: ready e solution.token. Um taskId sozinho não é uma solução concluída. A referência de recuperação de resultado explica o tratamento da resposta que a sua integração existente já deve realizar.

Para monitoramento, mantenha um ID de workflow e um task ID do solver separadamente. Uma única operação de navegador aprovada pode criar mais de uma tentativa de resolução. Conte essas tentativas individualmente para as métricas do solver, mas conte a operação original apenas uma vez ao relatar a conclusão do workflow.

Mantenha visíveis as falhas e tasks não finalizadas

Escolha um prazo de observação para cada coorte de tentativas e relate tasks bem-sucedidas, falhas e não resolvidas em conjunto. Uma coorte significa o mesmo grupo selecionado de requisições, como tasks enviadas durante uma determinada hora para um workflow aprovado.

Para uma taxa de resultado conservadora, divida os resultados bem-sucedidos do solver por todas as tentativas enviadas nessa coorte. Mostre também a contagem de tasks não resolvidas; uma taxa de resultado medida enquanto muitas tasks ainda estão em execução é provisória. Se você calcular uma taxa de tasks concluídas, identifique de forma explícita esse denominador mais restrito.

Agrupe erros de criação e de resultado usando as respostas de erro documentadas pela CapSolver. Uma configuração rejeitada e uma resolução malsucedida exigem investigações diferentes. Ambas podem afetar o serviço que o cliente experimenta, mas devem manter causas distintas.

Separe a validação do token da conclusão no navegador

A validação do token mede se o backend da aplicação protegida aceita o token Turnstile por meio do Siteverify.

As métricas de validação de token da Cloudflare contam requisições ao Siteverify e respostas com success: true ou success: false. Quando esses registros estiverem disponíveis, relate respostas válidas divididas por todas as respostas de validação na coorte selecionada. Mantenha falhas de rede sem resposta em uma contagem separada e visível.

O glossário de token explica o papel geral de um token. Neste fluxo, receber o token é um evento intermediário. A aplicação ainda precisa validá‑lo e concluir sua própria operação.

Quando o seu serviço não controla o site

Use um resultado observável da aplicação, como a página de confirmação esperada ou o registro permitido solicitado. Rotule isso como “workflow concluído”, com a asserção que confirmou essa conclusão.

Não deduza uma resposta do Siteverify a partir de um widget verde, de um status HTTP de sucesso ou do desaparecimento de um desafio. Se o cliente não tiver fornecido evidência de validação, relate a validação de token como indisponível. Uma observação ausente bem definida é mais útil do que uma taxa de sucesso estimada apresentada como se fosse medida.

Para relatórios ao cliente, mantenha o motivo original da falha quando o resultado final permanecer desconhecido. “O solver retornou um token; confirmação não observada antes do prazo” indica ao próximo engenheiro por onde começar.

Resgate Seu Código de Bônus CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código de bônus CAP26 ao recarregar sua conta CapSolver para obter 5% de bônus extra em cada recarga — sem limites.
Resgate agora no seu Painel CapSolver

Meça a latência no passo em que o atraso ocorre

O monitoramento de latência deve distinguir o tempo de espera do solver, o atraso na transferência do token e o tempo total do workflow.

Inicie o cronômetro do solver quando o cliente enviar a requisição da task e pare quando o cliente receber o resultado esperado ou uma falha final. Isso mede o tempo decorrido observado pelo cliente, incluindo rede e atraso de polling. Não isola o tempo de processamento interno do provedor.

Acompanhe separadamente o intervalo entre receber o token e enviar a requisição da aplicação. Um job de navegador que fica em fila após resolver pode criar um problema de token mesmo que o solver tenha respondido rapidamente.

A referência de validação server-side da Cloudflare declara que tokens Turnstile expiram após 300 segundos e são de uso único. A mesma referência explica erros de validação e a checagem de campos relevantes da resposta, incluindo o hostname e a ação esperados. Seu timestamp de recebimento é útil para diagnosticar atrasos na transferência; ele não prova o tempo exato de vida restante do token.

Mostre uma mediana e um percentil de cauda mais lenta, como p95, para tentativas concluídas comparáveis. Adicione a contagem de amostras e a contagem de timeouts ao lado delas. Um gráfico de latência apenas de sucessos pode parecer mais rápido quando as requisições mais lentas atingiram timeout e desapareceram do cálculo.

Mantenha distinguíveis testes locais, workers em nuvem, famílias de páginas diferentes e versões de integração alteradas. Compare o mesmo workflow antes e depois de um deploy antes de atribuir a mudança a um provedor global.

Use um pequeno dashboard com denominadores claros

Um primeiro dashboard útil conecta cada métrica a um evento que você consegue verificar.

Essas são definições em nível de aplicação, não afirmações de que todo campo é fornecido por uma resposta da API CapSolver. Calcule apenas o que seus logs e registros de cobrança suportarem. Quando o denominador de conclusão for zero, exiba o custo por operação concluída como indisponível em vez de forçar um número enganoso.

Calcule taxas de sucesso do Turnstile com Python

Python pode resumir uma exportação redigida da sua integração de solver existente sem enviar outra requisição de resolução.

Este exemplo usa apenas a biblioteca padrão do Python 3; não é necessário instalar pacotes nem usar credenciais de API. Ele mede os registros que você fornecer. Não coleta tasks ao vivo, não valida tokens nem mede o desempenho de um provedor por conta própria.

Prepare uma linha por tentativa de resolução

Exporte um snapshot em um prazo de observação definido. Use um attempt_id interno mesmo quando a criação da task falhar antes de a API retornar um task ID. Inclua todas as tentativas na sua coorte de workflow selecionada, incluindo falhas de criação e tasks ainda pendentes. Não exporte cada resposta de polling como uma tentativa separada.

Os campos CSV abaixo são um esquema de relatório de aplicação, não parâmetros da API CapSolver:

• solver_result: use ready apenas depois que sua integração receber um resultado ready bem-sucedido com o token esperado; use failed para um erro final e pending para trabalho não resolvido no momento do snapshot.
• validation: use passed ou failed apenas para uma resposta de validação de backend observada. Use unknown quando a evidência estiver indisponível, a validação ainda não tiver sido executada ou nenhuma resposta tiver chegado. Mantenha detalhes de erro de transporte em seus logs diagnósticos separados.
• workflow_completed: use yes apenas quando o resultado esperado da aplicação tiver sido confirmado. Use o mesmo workflow_id em todas as novas tentativas.

Salve este conjunto de dados ilustrativo como attempts.csv. Esses cinco registros são exemplos inventados, não observações de produção nem resultados de benchmark:

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

Execute o resumo

Salve o script a seguir como summarize_turnstile.py. A verificação de IDs duplicados impede que uma exportação contendo linhas repetidas de polling infle silenciosamente as contagens.

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))

Execute o script a partir do diretório que contém ambos os arquivos:

python3 summarize_turnstile.py attempts.csv

A amostra produz:

{
  "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
}

Três das cinco tentativas produziram um resultado do solver, portanto a taxa de resultados do solver da amostra é de 60%. Duas das três validações observadas foram aprovadas, resultando em 66,67%. Dois dos quatro fluxos de trabalho únicos foram concluídos, resultando em 50%. A tentativa com falha e a nova tentativa bem-sucedida para w2 contam como duas tentativas, mas apenas um fluxo de trabalho concluído.

A contagem pendente torna o resultado de 60% provisório. Reconstrua o snapshot depois que o trabalho pendente terminar; não acrescente outra linha com o mesmo ID de tentativa. Se não houver linhas ou não houver validações observadas, a taxa correspondente é null em vez de um zero fabricado.

Para um relatório por janela de tempo, selecione primeiro os fluxos de trabalho e inclua suas tentativas relevantes até o prazo de observação. Filtrar linhas de tentativas arbitrárias pode deixar de fora um sucesso anterior ou uma nova tentativa posterior e alterar o denominador de fluxos de trabalho. Mantenha uma contagem separada de fluxos de trabalho elegíveis que nunca chegaram ao envio para o solver; este pequeno script não consegue contar operações ausentes na sua entrada.

O cálculo local do exemplo pode ser reproduzido sem credenciais. Para monitorar seu serviço, substitua o exemplo por registros editados da sua integração real e documente a coorte da exportação e o prazo de observação. Evite incluir chaves de API, tokens brutos, cookies ou conteúdos de formulários pessoais.

Transforme mudanças de métrica em uma investigação específica

Investigue o primeiro estágio cujo resultado mudou, usando a mesma coorte de fluxos de trabalho em todo o processo.

Se os erros de criação de tarefas aumentarem, inspecione a configuração e as credenciais antes de aumentar as contagens de tentativas. Se os resultados do solver permanecerem estáveis, mas as falhas de validação crescerem, revise as categorias de erro de validação e o timing da transferência de tokens. Se a validação permanecer estável, mas a conclusão da aplicação cair, inspecione a asserção final, a resposta do formulário ou a saída de dados permitida.

Por exemplo, um provedor de QA pode notar que uma versão do cliente adiciona uma operação em segundo plano entre o recebimento do token e o envio do formulário. A comparação útil é o atraso na transferência desse cliente e os resultados de validação antes e depois da versão. Uma porcentagem agregada de sucesso em todos os clientes pode ocultar a jornada afetada.

Trate esses cenários como caminhos de investigação, não como prova de causa. Verifique um pequeno número de falhas autorizadas com carimbos de tempo antes de alterar a integração. Mantenha as novas tentativas limitadas e preserve a tentativa original para que as novas tentativas não inflacionem a contagem de conclusões.

A Cloudflare fornece sitekeys e secret keys de teste para verificações de implementação controladas. Use-as para testar os ramos de sucesso e falha da sua própria aplicação. Mantenha testes com tokens fictícios fora de relatórios reais de desempenho do solver: eles verificam o comportamento da aplicação, não a qualidade de resolução em produção.

Evite armazenar tokens de solução brutos, chaves de API, cookies ou conteúdos de página desnecessários em logs de monitoramento. Identificadores de fluxo de trabalho, identificadores de tarefa, carimbos de tempo, categorias de resultado e rótulos de configuração seguros geralmente fornecem um ponto de partida melhor.

Comece com o resultado de que o seu cliente precisa

Inicie o monitoramento do Turnstile com três perguntas separadas: o solver retornou seu resultado, a aplicação validou o token onde essa evidência está disponível, e a operação aprovada foi concluída?

Adicione latência e custo depois que esses resultados tiverem definições estáveis. Uma integração existente do CapSolver pode fornecer os eventos de tarefa do solver; sua aplicação fornece a evidência de conclusão. Manter essa divisão visível torna o troubleshooting e os relatórios para o cliente mais fáceis sem criar um sistema de monitoramento exagerado.

FAQ

P: Quais métricas do solver do Cloudflare Turnstile devo rastrear primeiro?

Rastreie a taxa de resultados do solver, a conclusão de fluxos de trabalho e o tempo até um resultado observado pelo cliente. Adicione os resultados de validação do Siteverify quando você operar o backend protegido ou tiver acesso autorizado aos logs dele. Sempre exiba falhas e tentativas não resolvidas.

P: Uma tarefa pronta no CapSolver significa que o site aceitou o token?

Não. Uma tarefa pronta com o token esperado confirma um resultado do solver. A validação no site e a operação final da aplicação são eventos posteriores que precisam de sua própria evidência.

P: Posso medir o sucesso da validação de token em um site que eu não opero?

Somente quando o proprietário fornecer evidências de validação autorizadas. Caso contrário, relate o resultado do navegador que você pode observar e marque a validação no backend como indisponível.

P: Por que a validação do Turnstile pode falhar após uma resposta rápida do solver?

Reutilização de token, envio atrasado ou problemas de implementação ainda podem afetar a validação. Inspecione o erro real e o timing da aplicação; a entrega rápida do token não estabelece que todas as etapas posteriores estavam corretas.

P: As taxas de sucesso do exemplo são promessas de desempenho?

Não. Os números de exemplo ilustram denominadores diferentes. Meça seus próprios fluxos de trabalho autorizados em condições comparáveis e mantenha o tráfego com chaves de teste separado das observações de produção.