Skip to main content

​
Enabling metrics

proxy-hopper run --config config.yaml --metrics --metrics-port 9090
Or via config: 
server:
  metrics: true
  metricsPort: 9090
Metrics are served at http://localhost:9090/metrics.

​
Metrics reference

​
Request metrics

MetricTypeLabelsDescription
proxy_hopper_requests_totalCountertarget, outcome, tagTotal proxied requests
proxy_hopper_request_duration_secondsHistogramtargetOutbound request latency
proxy_hopper_responses_totalCountertarget, status_code, tagUpstream HTTP responses by status code
proxy_hopper_retries_totalCountertargetRetry attempts
proxy_hopper_retry_exhaustions_totalCountertargetRequests that exhausted all retries
proxy_hopper_active_connectionsGauge—Open client connections
outcome values: success, rate_limited, server_error, connection_error, no_match. The tag label is set from the X-Proxy-Hopper-Tag request header (empty string if not provided).

​
Queue metrics

MetricTypeLabelsDescription
proxy_hopper_queue_depthGaugetargetRequests waiting for a free IP
proxy_hopper_queue_wait_secondsHistogramtargetTime spent waiting in the queue
proxy_hopper_queue_expired_totalCountertargetRequests dropped due to queue timeout

​
IP pool metrics

MetricTypeLabelsDescription
proxy_hopper_available_ipsGaugetargetIPs currently available in pool
proxy_hopper_quarantined_ipsGaugetargetIPs currently quarantined
proxy_hopper_ip_quarantine_events_totalCountertarget, address, provider, regionQuarantine events per IP
proxy_hopper_ip_failure_countGaugetarget, address, provider, regionConsecutive failure count per IP

​
Probe metrics

MetricTypeLabelsDescription
proxy_hopper_probe_success_totalCounteraddress, provider, regionSuccessful background probes
proxy_hopper_probe_failure_totalCounteraddress, provider, region, reasonFailed background probes
proxy_hopper_probe_duration_secondsHistogramaddress, provider, regionBackground probe latency
proxy_hopper_ip_reachableGaugeaddress, provider, region1 if IP passed last probe, 0 if not
Probe reason values: timeout, proxy_unreachable, connection_error, http_error.

​
Labels

​
tag label

Set by the X-Proxy-Hopper-Tag request header. Use it to identify which endpoints are consuming IPs or triggering quarantine events: 
session.headers["X-Proxy-Hopper-Tag"] = "search-api"

# Which endpoint hits rate limits most?
sum by (tag) (rate(proxy_hopper_requests_total{outcome="rate_limited"}[5m]))

# Response status breakdown by endpoint
sum by (tag, status_code) (rate(proxy_hopper_responses_total[5m]))

​
provider and region labels

Come from proxyProviders config — enable per-provider and per-region queries: 
# Average probe latency by region
avg by (region) (proxy_hopper_probe_duration_seconds)

# Quarantine rate by provider
rate(proxy_hopper_ip_quarantine_events_total[5m]) by (provider)

# Request success rate by target
rate(proxy_hopper_requests_total{outcome="success"}[5m])
  / rate(proxy_hopper_requests_total[5m])

​
Kubernetes scraping

See Kubernetes Monitoring for Prometheus Operator ServiceMonitor configuration and pod annotation-based scraping.