proxywhirl.metrics_collector

Prometheus metrics collector for ProxyWhirl.

This module provides centralized Prometheus metrics collection for monitoring proxy pool health, request performance, and circuit breaker states.

Metrics exposed: - proxywhirl_requests_total: Counter for total requests - proxywhirl_request_duration_seconds: Histogram for request latency - proxywhirl_proxy_health_status: Gauge for proxy health (1=healthy, 0=unhealthy) - proxywhirl_active_proxies: Gauge for number of active proxies - proxywhirl_circuit_breaker_state: Gauge for circuit breaker states

Usage:

from proxywhirl.metrics_collector import MetricsCollector

collector = MetricsCollector() collector.record_request(“success”, duration=1.5, proxy_id=”proxy-1”) collector.update_proxy_health(“proxy-1”, is_healthy=True)

Classes

MetricsCollector

Centralized Prometheus metrics collector for ProxyWhirl.

Functions

clear_proxy_metrics(proxy_id)

Clear all metrics for a specific proxy.

get_metrics_collector()

Get the global MetricsCollector singleton.

record_request(status, duration, proxy_id)

Record a request made through a proxy.

reset_metrics_collector()

Reset the global MetricsCollector singleton.

update_active_proxies(count)

Update the count of active proxies in the pool.

update_circuit_breaker_state(proxy_id, state)

Update circuit breaker state for a specific proxy.

update_proxy_health(proxy_id, is_healthy)

Update health status for a specific proxy.

Module Contents

class proxywhirl.metrics_collector.MetricsCollector(registry=None)[source]

Centralized Prometheus metrics collector for ProxyWhirl.

This class provides a clean API for recording metrics throughout the application. All metrics follow Prometheus naming conventions and best practices.

Initialize Prometheus metrics collectors.

Parameters:

registry (prometheus_client.CollectorRegistry | None) – Optional custom registry. If None, uses the default REGISTRY. This allows for isolated testing without metric collisions.

clear_proxy_metrics(proxy_id)[source]

Clear all metrics for a specific proxy.

This should be called when a proxy is removed from the pool to prevent stale metrics from persisting.

Parameters:

proxy_id (str) – Identifier of the proxy to clear

Return type:

None

record_request(status, duration, proxy_id)[source]

Record a request made through a proxy.

Parameters:

  • status (Literal['success', 'error', 'timeout']) – Request status (success, error, timeout)

  • duration (float) – Request duration in seconds

  • proxy_id (str) – Identifier of the proxy used

Return type:

None

update_active_proxies(count)[source]

Update the count of active proxies in the pool.

Parameters:

count (int) – Number of active proxies

Return type:

None

update_circuit_breaker_state(proxy_id, state)[source]

Update circuit breaker state for a specific proxy.

Parameters:

  • proxy_id (str) – Identifier of the proxy

  • state (Literal['closed', 'open', 'half-open']) – Circuit breaker state (closed=0, open=1, half-open=2)

Return type:

None

update_proxy_health(proxy_id, is_healthy)[source]

Update health status for a specific proxy.

Parameters:

  • proxy_id (str) – Identifier of the proxy

  • is_healthy (bool) – True if proxy is healthy, False otherwise

Return type:

None

proxywhirl.metrics_collector.clear_proxy_metrics(proxy_id)[source]

Clear all metrics for a specific proxy.

Convenience function that uses the global collector.

Parameters:

proxy_id (str) – Identifier of the proxy to clear

Return type:

None

proxywhirl.metrics_collector.get_metrics_collector()[source]

Get the global MetricsCollector singleton.

Returns:

The global metrics collector instance

Return type:

MetricsCollector

proxywhirl.metrics_collector.record_request(status, duration, proxy_id)[source]

Record a request made through a proxy.

Convenience function that uses the global collector.

Parameters:

  • status (Literal['success', 'error', 'timeout']) – Request status (success, error, timeout)

  • duration (float) – Request duration in seconds

  • proxy_id (str) – Identifier of the proxy used

Return type:

None

proxywhirl.metrics_collector.reset_metrics_collector()[source]

Reset the global MetricsCollector singleton.

This is primarily used for testing to ensure test isolation. Calling this function clears the global collector reference, allowing a new instance to be created on next access.

Return type:

None

proxywhirl.metrics_collector.update_active_proxies(count)[source]

Update the count of active proxies in the pool.

Convenience function that uses the global collector.

Parameters:

count (int) – Number of active proxies

Return type:

None

proxywhirl.metrics_collector.update_circuit_breaker_state(proxy_id, state)[source]

Update circuit breaker state for a specific proxy.

Convenience function that uses the global collector.

Parameters:

  • proxy_id (str) – Identifier of the proxy

  • state (Literal['closed', 'open', 'half-open']) – Circuit breaker state (closed=0, open=1, half-open=2)

Return type:

None

proxywhirl.metrics_collector.update_proxy_health(proxy_id, is_healthy)[source]

Update health status for a specific proxy.

Convenience function that uses the global collector.

Parameters:

  • proxy_id (str) – Identifier of the proxy

  • is_healthy (bool) – True if proxy is healthy, False otherwise

Return type:

None