Skip to content

Statistics

Cumulative client usage fed by the task-event stream. StatsCollector is a synchronous on_event handler that tallies solved/failed tasks and elapsed time per provider; snapshot() returns an immutable UsageStats.

Client usage statistics via an on_event-fed collector (ADR-0018).

A StatsCollector is a sync on_event handler: pass collector.on_event to Solver / AsyncSolver (constructor or per call) and it tallies the terminal task events into cumulative counts, elapsed time, and cost — per provider and per currency.

Terminal-event classification (events fire exactly one terminal event per solve invocation):

  • RESULT_RECEIVED → solved (carries cost in the adapter's currency).
  • PRE_FLIGHT_FAILED / SUBMIT_FAILED / RESULT_FAILED → failed.

Cost totals are currency-safe: ProviderUsage.cost sums only one adapter's costs (one currency per adapter instance), and UsageStats.cost_totals keys totals by currency code — there is never a blind cross-currency sum (ADR-0040). A threading.Lock keeps the counters safe for concurrent solves (ADR-0027 thread-safe client).

ProviderUsage dataclass

Cumulative usage for a single provider.

cost sums the solved tasks' prices for this provider (one currency per adapter instance); currency is that currency.

attempts property 

attempts

Solved + failed tasks for this provider.

UsageStats dataclass

Immutable usage snapshot (ADR-0040 currency-safe costs).

attempts property 

attempts

Solved + failed tasks across all providers.

StatsCollector

Cumulative solve/failure counters fed by task lifecycle events.

Use as an on_event handler — it is synchronous, so it works with both Solver and AsyncSolver:

.. code-block:: python

collector = StatsCollector()
with Solver([...], on_event=collector.on_event) as client:
    client.solve(...)
collector.snapshot()

on_event 

on_event(event)

Tally one task event; ignores non-terminal kinds.

snapshot 

snapshot()

An immutable copy of the current totals.

reset 

reset()

Zero all counters.