PythonでTurnstileソルバーの成功率を監視する方法

要約

• Turnstile のソルバー結果、トークン検証、アプリケーション完了を別々の結果として監視する。
• CapSolver の task ID はタスク作成の確認であり、期待したトークンを含む ready レスポンスが返ってはじめてソルバー結果が確定する。
• Cloudflare のウィジェット分析と自分のソルバーログは、異なるイベントを数えているため、定義を揃えずにパーセンテージを比較してはいけない。
• ソルバー結果が出るまでの時間と、アプリケーション最終結果までの時間を分けて測定し、失敗と未解決の試行も含める。
• 保護されたアプリケーションを自分で運用しているか、その検証ログへの権限あるアクセスがある場合にのみ、Siteverify の証跡を用いる。
• Python のサマリーでは 1 試行につき 1 レコードを使い、再実行されたワークフローはアプリケーション完了としては 1 回だけ数える。

スケジュール実行されるブラウザジョブが Turnstile トークンを受け取るものの、ページが期待される確認画面まで到達しないことがある。ソルバーダッシュボードは正常に見える一方で、運用チームは依然としてジョブ失敗を観測している。この場合、どちらの数字を信じるべきだろうか。

両方とも正しい可能性がある。ソルバーは結果を返したが、アプリケーションが完了を確認していないのである。有用な Cloudflare Turnstile ソルバーメトリクスは、これらの結果がどこで乖離しているかを示す。CapSolver は解答タスクのレスポンスを提供し、ブラウザのワークフローと、利用可能であれば保護対象アプリケーションのバックエンドが残りの証跡を提供する。このガイドでは、既存の認可済みインテグレーションで何を記録すべきかと、マスク済みログエクスポートを Python で要約する方法を説明する。第三者サイトのプライベート分析へのアクセスがないことを前提に、QA チームやエンタープライズ自動化サービス向けの実務的なモニタリングに焦点を当てる。

Turnstile ダッシュボードが実際に観測できる範囲を定義する

監視できる範囲は、保護された Web サイト、オートメーションクライアント、あるいはその両方のどれを自分が管理しているかに依存する。

アプリケーション所有者であれば、ウィジェットのアクティビティ、サーバー側の検証、最終的なアプリケーション処理を確認できる。承認されたクライアントジャーニー上で動く自動化サービスは、自分のソルバー応答とブラウザ結果しか見えないかもしれない。「検証済み」とラベル付けする前に、クライアントとどのバックエンド証跡が利用可能か合意しておくこと。

Cloudflare の チャレンジ結果分析 は、発行および解決されたチャレンジを、対話型・非対話型を含めて記述する。これらはウィジェットから見た観測値であり、外部 CAPTCHA ソルバーが何件のタスクを受け付け、完了させたかを直接報告するものではない。

レポートでは、Turnstile ウィジェットとフルページの Cloudflare チャレンジを分けて扱うこと。チームがどのチェックポイントに遭遇しているか不明な場合は、試行をまとめる前に Turnstile と Cloudflare チャレンジの見分け方 を参照する。異なるチャレンジ種別を混ぜると、ワークロードの変化があたかもソルバー品質の変化であるかのように見えてしまう。

ソルバーへのリクエストとその終端結果を記録する

ソルバー結果メトリクスでは、明確に定義した送信試行集合において、期待通りの解答が返ってきたタスク数を数えるべきである。

公式の CapSolver Turnstile API ガイド では、必須入力として websiteURL と websiteKey を持つ AntiTurnstileTaskProxyLess が説明されている。オプションのメタデータとして、ウィジェットの action と cdata 値がある。設定変更を後から失敗と比較できるよう、使用した構成を安全に識別できる情報を記録しておくこと。

CapSolver では、createTask でタスクを送信し、getTaskResult で結果を取得する。ドキュメント化された Turnstile 結果には status: ready と solution.token が含まれる。taskId だけでは解答が完了したことにはならない。結果取得リファレンス に、既存インテグレーションが既に実装しているはずのレスポンス処理が説明されている。

モニタリング用途では、ワークフロー ID とソルバーの task ID を別々に保持する。一つの承認済みブラウザ操作でも、複数の解答試行が作られることがある。ソルバーメトリクスではそれら試行を個別に数える一方で、ワークフロー完了のレポートでは元の操作を 1 回として数える。

失敗と未完了タスクを可視化したままにする

各試行グループ（コホート）に観測期限を定め、その中の成功・失敗・未解決タスクをまとめて報告する。コホートとは、特定時間帯に送信されたタスク群や、一つの承認済みワークフローなど、同じ基準で選んだリクエスト集合を指す。

保守的な結果率を出すには、そのコホートで送信されたすべての試行数で成功ソルバー結果数を割る。また、未解決数も表示すること。多くのタスクがまだ進行中の段階で算出された結果率は暫定値である。完了タスクのみを分母とする完了タスク率を計算する場合は、定義上の分母が狭いことを明示しておく。

作成エラーと結果エラーは、CapSolver のドキュメントにあるエラーレスポンス を用いて分類する。却下された構成と解答失敗では、調査すべき内容が異なる。どちらもクライアントが体験するサービス品質に影響し得るが、原因は分けて保持すべきである。

トークン検証とブラウザ完了を分離する

トークン検証とは、保護されたアプリケーションのバックエンドが Siteverify を通じて Turnstile トークンを受け入れるかどうかを測定することである。

Cloudflare の トークン検証メトリクス は、success: true または success: false を返した Siteverify リクエストとレスポンスをカウントする。これらの記録が利用可能な場合、選択したコホート内の全検証レスポンスに対する成功レスポンスの割合を報告する。レスポンスがないネットワーク失敗は、別枠で可視化したカウントとして保持する。

トークン用語集 では、トークンの一般的な役割が説明されている。このワークフローでは、トークンの受領は中間イベントに過ぎない。アプリケーションはそれを検証し、自身の処理を完了させる必要がある。

自分のサービスが Web サイトを管理していない場合

期待される確認ページの到達や、要求した許可済みレコードの取得といった、観測可能なアプリケーション結果を用いる。これを「ワークフロー完了」とラベル付けし、何をもって完了と見なしたかを明示する。

緑色になったウィジェット、HTTP 成功ステータス、チャレンジの消失などから Siteverify レスポンスを推測してはならない。クライアントから検証証跡が提供されていない場合は、トークン検証は「不明」と報告する。推定値をあたかも実測値のように提示するよりも、欠測が明確な観測の方が有用である。

クライアント向けレポートでは、最終結果が不明な場合も元の失敗理由を保持する。「ソルバーはトークンを返却したが、締切までに確認を観測できなかった」と記載しておけば、次のエンジニアがどこから調査を始めればよいかが分かる。

CapSolver ボーナスコードを利用しよう

自動化予算を今すぐ増量！
CapSolver アカウントにチャージする際にボーナスコード CAP26 を使用すると、すべてのチャージ額に対して 5% のボーナス が無制限で付与されます。
今すぐ CapSolver ダッシュボード で引き換えましょう。

遅延は発生しているステップごとに計測する

遅延モニタリングでは、ソルバー待ち時間、トークン受け渡しの遅延、ワークフロー全体の時間を区別する必要がある。

ソルバータイマーは、クライアントがタスクリクエストを送信した時点から開始し、期待した結果または終端エラーを受信した時点で停止する。これは、ネットワークおよびポーリングの遅延を含めた、クライアント視点の経過時間を測定するものであり、プロバイダ内部の処理時間だけを切り出すものではない。

トークン受信からアプリケーションリクエスト送信までの間隔は別途記録する。解答後にキュー待ちが発生するブラウザジョブでは、ソルバーが素早く応答していても、トークン側で問題が発生し得る。

Cloudflare の サーバー側検証リファレンス では、Turnstile トークンは 300 秒で期限切れとなり、1 回限り有効であると明記されている。同リファレンスには、検証エラーや、想定されるホスト名・action などの関連レスポンスフィールドの確認方法も説明されている。受信タイムスタンプは受け渡し遅延の診断には有用だが、トークンの残存有効期間を正確に証明するものではない。

完了試行の中で比較可能な集合について、中央値と p95 のような遅い側のパーセンタイルを示すこと。併せてサンプル数とタイムアウト数も表示する。成功のみを対象にしたレイテンシチャートは、最も遅いリクエストがすべてタイムアウトして計算から外れている場合、見かけ上速くなってしまう。

ローカルテスト、クラウドワーカー、ページ種別、インテグレーションバージョンの違いは区別できるように保つ。グローバルなプロバイダ変更を疑う前に、同一ワークフローをデプロイ前後で比較すること。

分母が明確な小さなダッシュボードを 1 つ作る

有用な最初のダッシュボードは、各メトリクスを検証可能なイベントに結びつけている。

これらはアプリケーションレベルでの提案定義であり、すべての項目が CapSolver API レスポンスで提供されるという意味ではない。自分のログと請求記録で算出可能なものだけを計算すること。完了処理の分母が 0 の場合は、完了処理あたりコストを無理に数値化せず「不明」として表示する。

Python で Turnstile の成功率を計算する

Python を用いれば、既存のソルバーインテグレーションからエクスポートしたマスク済みデータを、追加の解答リクエストを送らずに要約できる。

以下の例は Python 3 の標準ライブラリのみを使用し、パッケージのインストールや API クレデンシャルは不要である。あくまで、与えられた記録を集計するだけであり、ライブタスクの収集やトークン検証、プロバイダの性能測定を自動的に行うものではない。

解答試行 1 件につき 1 行を用意する

あらかじめ観測期限を決め、その時点でのスナップショットをエクスポートする。API が task ID を返す前にタスク作成が失敗する場合でも、内部的な attempt_id を付与する。選択したワークフローコホートに属するすべての試行を、作成失敗や未解決タスクも含めて抽出する。ポーリング結果ごとに別試行として出力してはならない。

以下の CSV フィールドはアプリケーションレポート用のスキーマであり、CapSolver API のパラメータではない。

• solver_result：期待したトークン付きの ready 結果をインテグレーションが受信した場合のみ ready を使う。終端エラーには failed を、スナップショット時点で未解決の作業には pending を使う。
• validation：バックエンドの検証レスポンスが観測できた場合にのみ passed または failed を用いる。証跡が得られない、検証未実行、レスポンス未着のいずれかの場合は unknown を使用する。通信エラーの詳細は別の診断ログで保持する。
• workflow_completed：想定したアプリケーション結果が確認できた場合のみ yes を用いる。再試行でも同一ワークフローには同じ workflow_id を付与する。

次のサンプルデータセットを attempts.csv として保存する。これら 5 レコードはあくまで例示用であり、本番観測値やベンチマーク結果ではない。

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

サマリーを実行する

次のスクリプトを summarize_turnstile.py として保存する。重複 ID チェックにより、ポーリング行が重複して含まれていても、カウントが水増しされるのを防ぐ。

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

両ファイルを含むディレクトリで、次のコマンドを実行する。

python3 summarize_turnstile.py attempts.csv

このサンプルは次の結果を出力する。

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

5 回の試行のうち 3 回でソルバー結果が生成されたため、このサンプルのソルバー結果率は 60% です。観測されたバリデーション 3 回のうち 2 回が成功し、66.67% となります。ユニークなワークフロー 4 件のうち 2 件が完了し、50% となります。w2 の失敗した試行と成功した再試行は 2 回の試行として数えますが、完了したワークフローとしては 1 件です。

保留中の件数があるため、この 60% の結果は暫定値です。未完了の作業が終わったらスナップショットを再作成し、同じ試行 ID の行を追加しないでください。行が 1 つもない場合や、観測されたバリデーションがない場合、そのレートは 0 をでっち上げるのではなく null とします。

時間ウィンドウレポートを作成する場合は、まずワークフローを選択し、観測期限までに関連する試行を含めてください。任意の試行行をフィルタリングすると、前の成功や後の再試行が抜け落ち、ワークフローの分母が変わってしまう可能性があります。ソルバー送信に到達しなかった対象ワークフローの件数は別途カウントしてください。この小さなスクリプトは、入力に含まれていないオペレーションを数えることはできません。

例のローカル計算は、認証情報なしで再現できます。自分のサービスを監視するには、このサンプルを実際のインテグレーションから取得した編集済みレコードに置き換え、エクスポートのコホートと観測期限を文書化してください。API キー、生のトークン、クッキー、個人の入力内容は含めないようにしてください。

メトリクス変化を具体的な調査に落とし込む

同じワークフローコホートを通して、結果が変化した最初のステージを調査してください。

タスク作成エラーが増えた場合は、リトライ回数を増やす前に設定と認証情報を調べてください。ソルバーの結果が安定している一方でバリデーション失敗が増えている場合は、バリデーションエラーのカテゴリとトークン引き渡しのタイミングを確認してください。バリデーションが安定しているのにアプリケーション完了率が下がっている場合は、最終アサーション、フォームの応答、許可されたデータ出力を調査してください。

たとえば、QA プロバイダが、クライアントのリリースによってトークン受領とフォーム送信の間にバックグラウンド処理が追加されたことに気づくかもしれません。有用な比較は、そのクライアントにおけるリリース前後のハンドオフ遅延とバリデーション結果です。全クライアントを一括した合計成功率では、その影響を受けたユーザージャーニーが隠れてしまうことがあります。

こうした状況は原因の証拠ではなく、調査の道筋として扱ってください。インテグレーションを変更する前に、タイムスタンプ付きの少数の認可された失敗ケースを確認してください。リトライは上限を設け、完了件数を水増ししないように元の試行を保持してください。

Cloudflare は、制御された実装チェックのために テスト用サイトキーとシークレットキー を提供しています。これらを使用して、自分のアプリケーションにおける成功パスと失敗パスをテストしてください。ダミートークンによるテストは、ソルバーの本番パフォーマンスレポートからは除外してください。これらはアプリケーションの挙動を検証するものであり、本番環境における解決品質を測るものではありません。

監視ログには、生のソリューショントークン、API キー、クッキー、不要なページ内容を保存しないでください。ワークフロー ID、タスク ID、タイムスタンプ、結果カテゴリ、安全な構成ラベルなどの方が、通常はよりよい出発点となります。

クライアントが必要とする結果から始める

Turnstile のモニタリングは、次の 3 つの質問から始めてください。ソルバーは結果を返したか、その証拠が利用できる箇所でアプリケーションはトークンを検証したか、承認された処理は完了したか、の 3 点です。

それらの結果の定義が安定してから、レイテンシとコストを追加してください。既存の CapSolver インテグレーションは、ソルバータスクのイベントを提供できます。アプリケーション側は完了の証拠を提供します。その分業を明確に保つことで、過剰に大きな監視システムを構築しなくても、トラブルシューティングやクライアント向けレポートを容易にできます。

FAQ

Q: まずどの Cloudflare Turnstile ソルバーメトリクスを追跡すべきですか？

ソルバー結果率、ワークフロー完了率、クライアントから見た結果取得までの時間を追跡してください。保護されたバックエンドを運用している、あるいはそのログへの認可されたアクセスがある場合は、Siteverify のバリデーション結果も追加します。失敗と未解決の試行は常に表示してください。

Q: CapSolver タスクが ready になっていれば、そのサイトはトークンを受け入れたという意味ですか？

いいえ。期待されるトークンを伴う ready タスクは、ソルバー結果が得られたことを示すだけです。サイトでのバリデーションと最終的なアプリケーション処理は、その後に行われる別のイベントであり、別個の証拠が必要です。

Q: 自分が運用していないサイトで、トークンバリデーションの成功を測定できますか？

サイトの所有者が認可されたバリデーションの証拠を提供する場合のみ可能です。それ以外の場合は、ブラウザから観測できる結果を報告し、バックエンドバリデーションは「利用不可」とマークしてください。

Q: 速いソルバー応答のあとで Turnstile バリデーションが失敗するのはなぜですか？

トークンの再利用、送信の遅延、実装上の問題などにより、バリデーションは依然として影響を受ける可能性があります。実際のエラー内容とアプリケーションのタイミングを確認してください。トークンが速く届けられたこと自体は、その後のすべてのステップが正しかったことを保証しません。

Q: 例に出ている成功率は性能保証ですか？

いいえ。これらの数字は、分母の違いを示すための例です。自分が認可を受けたワークフローを、同等の条件下で測定し、テストキーのトラフィックは本番観測から分離してください。